www.digitalmars.com         C & C++   DMDScript  

digitalmars.D - Doxygen / documentation - what are the latest & best tools?

reply "Matthew" <admin.hat stlsoft.dot.org> writes:
I'm trying to get some D stuff documented, and the old dfilter from a couple of
years ago just had to be replaced. I've 
used Stewart's update but it, or at least the version I have, isn't quite up to
it either.

Does anyone have anything out there that can help me in the short term?

Cheers

Matthew
Sep 29 2004
next sibling parent reply Burton Radons <burton-radons smocky.com> writes:
Matthew wrote:
 I'm trying to get some D stuff documented, and the old dfilter from a couple
of years ago just had to be replaced. I've 
 used Stewart's update but it, or at least the version I have, isn't quite up
to it either.
 
 Does anyone have anything out there that can help me in the short term?

What're the deficiencies of the support in Doxygen? It ate a whole library I threw at it without complaint, although I don't use templates.
Sep 29 2004
next sibling parent reply Stewart Gordon <Stewart_member pathlink.com> writes:
In article <cje8dg$s3s$1 digitaldaemon.com>, Burton Radons says...
<snip>
 What're the deficiencies of the support in Doxygen?  It ate a whole 
 library I threw at it without complaint, although I don't use 
 templates.

I found quite a lot of problems. Dfilter fixes: - requires a semicolon between class definitions - garbage 'import' and 'module' declarations in the output Dfilter partly fixes: - can't see attribute blocks - doesn't know the words 'alias', 'function', 'delegate' and 'interface' Dfilter doesn't (yet?) fix: - doesn't know the words 'version' and 'debug' - doesn't recognise that 'this' is a constructor (I'd think it's supposed to group constructors under a heading, but I'm not sure) - last time I looked, didn't recognise inner structs and unions - doesn't recognise D /+ ... +/ comments as comments Someone seemed to think that Doxygen handles D as a cross between C++, C# and Java or something, but I'm not convinced. It appears to parse D code pretty much, if not exactly, as C++. You're lucky to have managed to write a whole library without being bitten by any of these. Stewart.
Sep 29 2004
next sibling parent Sjoerd van Leent <svanleent wanadoo.nl> writes:
Stewart Gordon wrote:
 In article <cje8dg$s3s$1 digitaldaemon.com>, Burton Radons says...
 <snip>
 
What're the deficiencies of the support in Doxygen?  It ate a whole 
library I threw at it without complaint, although I don't use 
templates.

I found quite a lot of problems. Dfilter fixes: - requires a semicolon between class definitions - garbage 'import' and 'module' declarations in the output Dfilter partly fixes: - can't see attribute blocks - doesn't know the words 'alias', 'function', 'delegate' and 'interface' Dfilter doesn't (yet?) fix: - doesn't know the words 'version' and 'debug' - doesn't recognise that 'this' is a constructor (I'd think it's supposed to group constructors under a heading, but I'm not sure) - last time I looked, didn't recognise inner structs and unions - doesn't recognise D /+ ... +/ comments as comments Someone seemed to think that Doxygen handles D as a cross between C++, C# and Java or something, but I'm not convinced. It appears to parse D code pretty much, if not exactly, as C++. You're lucky to have managed to write a whole library without being bitten by any of these. Stewart.

If some of you want to help designing and developing a new revolutionary documentation generator, please go to: http://www.dsource.org/forums/viewtopic.php?t=363 Explanation about the project is available there. Regards, Sjoerd
Sep 29 2004
prev sibling parent reply Jason Mills <jmills cs.mun.ca> writes:
Rather than write/update a D filter, would Doxygen handle D source 
better if a Doxygen "front end" parser was written, as is done with Java?

Jason
Sep 29 2004
next sibling parent Stewart Gordon <Stewart_member pathlink.com> writes:
In article <cjecmm$vai$1 digitaldaemon.com>, Jason Mills says...

 Rather than write/update a D filter, would Doxygen handle D source 
 better if a Doxygen "front end" parser was written, as is done with 
 Java?

That would indeed improve matters considerably. But the output generation, and probably the internal code representation to go wtih it, might need to be improved to support some of D's features (e.g. to stop it calling every alias a type). Stewart.
Sep 29 2004
prev sibling parent pragma <pragma_member pathlink.com> writes:
In article <cjecmm$vai$1 digitaldaemon.com>, Jason Mills says...
Rather than write/update a D filter, would Doxygen handle D source 
better if a Doxygen "front end" parser was written, as is done with Java?

Jason

I think this is the way to go, seeing as how D has some fundamentally different things going for it that it's predecessors (C++ and Java) do not. In my efforts to write a d-build tool (yes, yet *another* one) I wanted something that fully followed version and debug statements in a way that the present crop of tools does not (plus I wanted to investigate parser technologies to a depth I hadn't before). It absolutely amazed me at how complex a .d file can get with just a few layers of versioning thrown in. I'm also using some custom pragmas to help steer the thing, and even that becomes quite a challenge since there are 4 different ways those can be declared as well. I'm sure that's just the beginning. Other things that come to mind are: auto classes, templates (obviously), public/private import behavior, and the three different styles of attribute blocks/statements. version(DNG) pragma(EricAnderton,"yahoo");
Sep 29 2004
prev sibling parent Bastiaan Veelo <Bastiaan.N.Veelo ntnu.no> writes:
I did not use dfilter, as I read somewhere that Doxygen >= 1.3.6 already 
covers the functionality of dfilter. But the documentation it generates 
is partly bogus. In 
http://svn.dsource.org/svn/projects/dcouple/trunk/managed/doc/index.html, 
I manually documented usage on the \mainpage.

Burton Radons wrote:

 What're the deficiencies of the support in Doxygen?  It ate a whole 
 library I threw at it without complaint, although I don't use templates.

Mixins pose a challenge. Documentation for the template itself needs to be generated, but also in all places were it is mixed in, taking into account aliased identifiers! #/*! Documentation for users of the template. */ #template Implementation() #{ # /*! Do something interesting with MyType. */ # void func( MyType t ) { /* ... */ } #} # #/*! Documentation for Japan class. */ #class Japan #{ # alias Sushi MyType; # mixin Implementation; #} # #/*! Documentation for Italy class. */ #class Italy #{ # alias Pasta MyType; # mixin Implementation; #} # #class Sushi {} #class Pasta {} Ideally, this should generate documentation like the following: --------------------------------------------- Template "Implementation" Documentation for users of the template. Arguments: none. Functions: void func( Mytype t): Do something interesting with MyType. etc. --------------------------------------------- Class "Japan" Documentation for Japan class. Public Members: void func( Sushi t ): Do something interesting with Sushi. --------------------------------------------- Class "Italy" Documentation for Italy class. Public Members: void func( Pasta t ): Do something interesting with Pasta.
Sep 29 2004
prev sibling parent "Ben Hinkle" <bhinkle mathworks.com> writes:
"Matthew" <admin.hat stlsoft.dot.org> wrote in message
news:cje3cp$p5o$1 digitaldaemon.com...
 I'm trying to get some D stuff documented, and the old dfilter from a

 used Stewart's update but it, or at least the version I have, isn't quite

 Does anyone have anything out there that can help me in the short term?

 Cheers

 Matthew

I gave up (for now) on doxygen/dfilter and have started just writing html by hand - well actually I borrowed the format of the phobos doc. It's pretty easy to cut-and-paste into the following template: <a name="$module$"> <h4>$module$</h4> <dl> <dt>class <b>$classname$</b>($templateparam$) <dd>$brief$ <p> <dl> <dt>$returntype$ <b>$functionname$</b>($args$); <dd>$brief$ <dt>$returntype$ <b>$functionname$</b>($args$); <dd>$brief$ ... repeat for all the public class members </dl> ... repeat for all the public module members </dl> ... repeat for all the modules in the package Once dfilter works out the kinks I'd like to switch back, assuming I can figure out how to customize it to reproduce basically what the template above does. good luck, -Ben
Sep 29 2004