www.digitalmars.com         C & C++   DMDScript  

D - idea -- inline docs ala Javadoc

reply "chris jones" <flak clara.co.uk> writes:
One of the things i liked about Java was the idea of Javadoc. So imo some
basic specs for inline comments that could be easily interpreted into
referance docs would be a good adition to D. I have never used Javadoc but i
think it parsed the source file and made a basic html page from the source,
and you put any extra info for Javadoc in coments in the source code. As
alot people do put coments in their code, if there was a spec for these
coments so they could be parsed by 'DDocGen' then i think they would use it.
As they would be comments then the compiler will ignore them, no extra work
for Walter :) And i am thinking a sophisticated Doc generater could scan
multiple files and generated a prety complex referance all nicely
crosslinked and such. Also it ocurs to me that it could be alot easier to
integrate the docs from diferant projects/librarys if the directory
structure follows the namespace structure. Its a long time since i used java
so i cant remember what the syntax of the coments were but i dont think it
needs to be very complicated., but it would need to be part of the D spec,

what do you think?

chris
Sep 10 2002
parent reply Pavel Minayev <evilone omen.ru> writes:
chris jones wrote:

 One of the things i liked about Java was the idea of Javadoc. So imo some

It was discussed already. See "Code documentation" threads. Right now, it's the syntax that's being discussed, there is no working doc generator yet.
Sep 10 2002
next sibling parent "chris jones" <flak clara.co.uk> writes:
Great :)

"Pavel Minayev" <evilone omen.ru> wrote in message
news:alljd6$gr7$3 digitaldaemon.com...
 chris jones wrote:

 One of the things i liked about Java was the idea of Javadoc. So imo


 It was discussed already. See "Code documentation" threads. Right now,
 it's the syntax that's being discussed, there is no working doc
 generator yet.

Sep 10 2002
prev sibling next sibling parent reply Burton Radons <loth users.sourceforge.net> writes:
Pavel Minayev wrote:

 chris jones wrote:
 
 One of the things i liked about Java was the idea of Javadoc. So imo some

It was discussed already. See "Code documentation" threads. Right now, it's the syntax that's being discussed, there is no working doc generator yet.

The working copy of my port produces some docs, but it's been delayed. The nice thing is that the fastest way to compile a large project is just to send all the files through dli (it's more than fast enough - the 400kb Phobos takes just 2.3 seconds, and could probably be brought under one if it did assembly itself), so project-wide documentation can be gathered rather easily. Plus, of course, the compiler knows the language better than any code generator could manage.
Sep 10 2002
parent "Walter" <walter digitalmars.com> writes:
"Burton Radons" <loth users.sourceforge.net> wrote in message
news:3D7E826C.9000504 users.sourceforge.net...
 The nice thing is that the fastest way to compile a large project is
 just to send all the files through dli (it's more than fast enough - the
 400kb Phobos takes just 2.3 seconds, and could probably be brought under
 one if it did assembly itself), so project-wide documentation can be
 gathered rather easily.

<g> D is designed for fast compiling.
Sep 11 2002
prev sibling parent reply andy <acoliver apache.org> writes:
Pavel Minayev wrote:
 chris jones wrote:
 
 One of the things i liked about Java was the idea of Javadoc. So imo some

It was discussed already. See "Code documentation" threads. Right now, it's the syntax that's being discussed, there is no working doc generator yet.

One thing is it might be nice to have an enhanced version of the html deal that can grab other defined tags inside of code and (assume XML basically) and use that as doco. Then others who chose could create stylized version through XSLT. Just a thought...
Sep 10 2002
parent Juarez Rudsatz <juarez nowhere.com> writes:
andy <acoliver apache.org> wrote in news:3D7E96DE.1000509 apache.org:

 One thing is it might be nice to have an enhanced version of the html 
 deal that can grab other defined tags inside of code and (assume XML 
 basically) and use that as doco.  Then others who chose could create 
 stylized version through XSLT.  Just a thought...

Have you seen the xml docbook format ? A compiler could extract the documentation from comments in source code and generate a xml docbook. Than you can use your favorite docbook transformer ( XSLT, Jade, ... ) for generating the final version.
Sep 11 2002