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

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.

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.

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

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

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.

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");

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.

"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