www.digitalmars.com         C & C++   DMDScript  

D - Documentation standard

reply "Matthew Wilson" <matthew-hat -stlsoft-dot.-org> writes:
What do we all feel about agreeing on Doxygen for the documentation tool for
the near future (i.e. next 12 months). I would further suggest that we elect
to go for

    /** Blah Blah */

rather than

  /// Blah Blah

which will make it easy to change to JavaDoc, if anyone gets sufficiently
motivated to write a D doclet.

Whatever convention we use now, it would be good to agree on one. If/when a
D-documenting tool is specifically written, it will make the implementation
simpler by having a small set of existing standards for which it will need
to provide backwards compatibility.

I used Doxygen for the std.windows.registry module, and I'm doing so again
with the std.io.recls one.

Thoughts?

Matthew
Nov 05 2003
next sibling parent reply J Anderson <REMOVEanderson badmama.com.au> writes:
Matthew Wilson wrote:

What do we all feel about agreeing on Doxygen for the documentation tool for
the near future (i.e. next 12 months). I would further suggest that we elect
to go for

    /** Blah Blah */

rather than

  /// Blah Blah

which will make it easy to change to JavaDoc, if anyone gets sufficiently
motivated to write a D doclet.

Whatever convention we use now, it would be good to agree on one. If/when a
D-documenting tool is specifically written, it will make the implementation
simpler by having a small set of existing standards for which it will need
to provide backwards compatibility.

I used Doxygen for the std.windows.registry module, and I'm doing so again
with the std.io.recls one.

Thoughts?

Matthew

  

Nov 05 2003
parent Ant <Ant_member pathlink.com> writes:
In article <bociu2$1tns$1 digitaldaemon.com>, J Anderson says...
Sounds good. I can't wait to see it become part of an editor/D IDE.

leds is open source, contributions are wellcome. and more: leds is quite simple because the main jobs is done by a ready available component: scintilla (and is supported by the excelent DUI toolkit, if I may say so myself) leds home page (Benji, where's the cdan?): http://ca.geocities.com/leds_editor/index.html Ant
Nov 06 2003
prev sibling next sibling parent reply "Lars Ivar Igesund" <larsivi stud.ntnu.no> writes:
"Matthew Wilson" <matthew-hat -stlsoft-dot.-org> wrote in message
news:bocd7f$1l7i$1 digitaldaemon.com...
 What do we all feel about agreeing on Doxygen for the documentation tool

 the near future (i.e. next 12 months).

I agree.
 I would further suggest that we elect
 to go for

     /** Blah Blah */

 rather than

   /// Blah Blah

 which will make it easy to change to JavaDoc, if anyone gets sufficiently
 motivated to write a D doclet.

Maybe I'm ignorant, but I don't see that JavaDoc is better than Doxygen in any way. Also, I like the Open Source nature of Doxygen. Maybe the filter you made could be submitted to the central Doxygen repository? It would give D support out of the box instead of downloading a D filter from somewhere else. Lars Ivar Igesund
Nov 05 2003
parent reply "Matthew Wilson" <matthew-hat -stlsoft-dot.-org> writes:
 which will make it easy to change to JavaDoc, if anyone gets


 motivated to write a D doclet.

Maybe I'm ignorant, but I don't see that JavaDoc is better than Doxygen in any way. Also, I like the Open Source nature of Doxygen. Maybe the filter you made could be submitted to the central Doxygen repository? It would give D support out of the box instead of downloading a D filter from somewhere else.

I wasn't suggesting it was. I have very little knowledge of JavaDoc beyond its basic use in Java itself. I was just giving an example. Since I wrote that post, I tried to use /** */ in the std.recls port, and I found it too hard, so was about to recind this little nugget. :) I like the idea of a Doxygen filter. Do you have a URL for writing Doxygen plug-ins? I've never got beyond the basic use of it
Nov 05 2003
parent "Lars Ivar Igesund" <larsivi stud.ntnu.no> writes:
"Matthew Wilson" <matthew-hat -stlsoft-dot.-org> wrote in message
news:bocr92$2am6$1 digitaldaemon.com...

 I like the idea of a Doxygen filter. Do you have a URL for writing Doxygen
 plug-ins? I've never got beyond the basic use of it

I only know the doxygen website: www.doxygen.org There are very many users around the world, so I guess the information shouldn't be to hard to come by. At least it's probably easy to get help to find it :) Lars Ivar Igesund
Nov 05 2003
prev sibling parent Jason Mills <jmills cs.mun.ca> writes:
Matthew Wilson wrote:
 What do we all feel about agreeing on Doxygen for the documentation tool for
 the near future (i.e. next 12 months).

I agree. I would further suggest that we elect
 to go for
 
     /** Blah Blah */
 
 rather than
 
   /// Blah Blah
 
 which will make it easy to change to JavaDoc, if anyone gets sufficiently
 motivated to write a D doclet.

No point in making /** comment */ standard for JavaDoc's sake. There are many other features in Doxygen people will use that is not compatible with JavaDoc. Personally I like ///.
 Whatever convention we use now, it would be good to agree on one. If/when a
 D-documenting tool is specifically written, it will make the implementation
 simpler by having a small set of existing standards for which it will need
 to provide backwards compatibility.
 
 I used Doxygen for the std.windows.registry module, and I'm doing so again
 with the std.io.recls one.
 
 Thoughts?
 
 Matthew
 
 

Nov 06 2003