www.digitalmars.com         C & C++   DMDScript  

digitalmars.D - Abstract DDoc output for better document generation

reply "Tolga Cakiroglu" <tcak pcak.com> writes:
After having some experience with documentation generation from
dmd command like, and seeing outputs, I wasn't satisfied with it.
Other alternatives as Doxygen is available, though it parses
codes itself that is not based on what version of DMD is
installed on system.

Since the structure of DDoc is already defined, instead of
generating HTML output, I would propose to generate an XML file
that contains meta data about codes and comments which can be
used by 3rd party documentation generator programmes to generate
HTML files. This way DDoc definitions can be simplified, better
looking documents can be generated much easily.
May 17 2014
next sibling parent "bearophile" <bearophileHUGS lycos.com> writes:
Tolga Cakiroglu:


 After having some experience with documentation generation from
 dmd command like, and seeing outputs, I wasn't satisfied with 
 it.


What problems have you found in that output?

Bye,
bearophile
May 17 2014
prev sibling parent reply "Mason McGill" <mmcgill caltech.edu> writes:
On Saturday, 17 May 2014 at 18:03:53 UTC, Tolga Cakiroglu wrote:

 After having some experience with documentation generation from
 dmd command like, and seeing outputs, I wasn't satisfied with 
 it.
 Other alternatives as Doxygen is available, though it parses
 codes itself that is not based on what version of DMD is
 installed on system.

 Since the structure of DDoc is already defined, instead of
 generating HTML output, I would propose to generate an XML file
 that contains meta data about codes and comments which can be
 used by 3rd party documentation generator programmes to generate
 HTML files. This way DDoc definitions can be simplified, better
 looking documents can be generated much easily.


Try compiling with the -X flag to generate a JSON file describing
the source. Add the -D flag if you want documentation comments in
the JSON output.

Hope that helps!
May 17 2014
parent reply =?UTF-8?B?U8O2bmtlIEx1ZHdpZw==?= <sludwig rejectedsoftware.com> writes:
Am 17.05.2014 20:28, schrieb Mason McGill:

 On Saturday, 17 May 2014 at 18:03:53 UTC, Tolga Cakiroglu wrote:

 After having some experience with documentation generation from
 dmd command like, and seeing outputs, I wasn't satisfied with it.
 Other alternatives as Doxygen is available, though it parses
 codes itself that is not based on what version of DMD is
 installed on system.

 Since the structure of DDoc is already defined, instead of
 generating HTML output, I would propose to generate an XML file
 that contains meta data about codes and comments which can be
 used by 3rd party documentation generator programmes to generate
 HTML files. This way DDoc definitions can be simplified, better
 looking documents can be generated much easily.


 Try compiling with the -X flag to generate a JSON file describing
 the source. Add the -D flag if you want documentation comments in
 the JSON output.

 Hope that helps!


Also see https://github.com/rejectedsoftware/ddox for DDOC compatible 
documentation generator that uses the JSON output. However, due to 
various shortcomings, of which not all are easy to resolve, I'm planning 
to instead directly use a D parser at some point.
May 18 2014
parent "Tolga Cakiroglu" <tcak pcak.com> writes:
 Also see https://github.com/rejectedsoftware/ddox for DDOC 
 compatible documentation generator that uses the JSON output. 
 However, due to various shortcomings, of which not all are easy 
 to resolve, I'm planning to instead directly use a D parser at 
 some point.


Yes, this seems like a good tool. Actually, the reason o my 
thought was to take as much meta data from codes as possible to 
generate much more useful information. Not for documentation 
only, and analysis as well. This would remove the burden of 
defining and updating document generator on DMD, and move it to 
external tools.
May 18 2014