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

  


Sounds good. I can't wait to see it become part of an editor/D IDE.
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


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.


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




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.


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