digitalmars.D - Standard documentation format
=?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
=?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 Side note: The C# documentation format was added to the specification... So it seems like at least *some* languages feel it's worth mentioning ? --anders
Apr 12 2005