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 

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 

 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!


#template Implementation()






#class Japan






#class Italy





#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


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


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