www.digitalmars.com         C & C++   DMDScript  

digitalmars.D - Standard documentation format

reply =?iso-8859-1?q?Knud_S=F8rensen?= <12tkvvb02 sneakemail.com> writes:
I would be nice if d had a standard documentation format.

It could be build from comments like with javadoc and doxygen
but should also use the unit test to generate code examples.

The good side of having a standard format is that it raises 
the common foundation we have to build on.

Writes of IDE's will only have to support one documentation format
which they can include into the help system.

Writers of d libraries will not have to worry 
about which type of documentation the clients are using, 
they will not have to support a number of different formats
and the docs can be shipped with the library binaries.

A common format will also help us make sure that it is easy 
to make good d documentation.
Apr 12 2005
parent =?ISO-8859-1?Q?Anders_F_Bj=F6rklund?= <afb algonet.se> writes:
Knud Sørensen wrote:


 I would be nice if d had a standard documentation format.
 
 It could be build from comments like with javadoc and doxygen
 but should also use the unit test to generate code examples.


If you look at the http://www.prowiki.org/wiki4d/wiki.cgi?JavaToD
page, down near the bottom, you can see one such suggested format.

(It doesn't add documentation for unittest and in/out/invariant
contracts just yet, but that could be added to Doxygen later on...)


It looks like this, in the "short form" (///) :

     /// frobnicates the foo
     ///  return the result
     int frobnicate();

     int bar; ///< stores the current bar value

The "long form" (/** */) is also just fine :

     /** frobnicates the foo
      *  return the result
      */
     int frobnicate();

     /** stores the current bar value */
     int bar;


Both of these forms are accepted by Doxygen.
(the "long form" is the same as JavaDoc uses)

More information available in the Doxygen manual:
http://www.stack.nl/~dimitri/doxygen/docblocks.html



So it seems like at least *some* languages feel it's worth mentioning ?

--anders
Apr 12 2005