www.digitalmars.com         C & C++   DMDScript  

digitalmars.D - Doxygen and D

reply =?ISO-8859-1?Q?Anders_F_Bj=F6rklund?= <afb algonet.se> writes:
Found out why doxygen didn't seem to support D,
the file suffix check in Doxygen 1.4.1 was flawed...

http://bugzilla.gnome.org/show_bug.cgi?id=169640

 Thanks, apparently you're the first D user that tries doxygen ;-)



With a little more effort, it shouldn't be at all
hard to make Doxygen support most of the D files.
(natively, without filtering into C++/Java first)

If you feel that you could help, then please do ?
(if nothing else, then just by running it with your
code and noting the areas that needs improvement?)

http://www.doxygen.org/

--anders
Mar 08 2005
parent reply Kris <Kris_member pathlink.com> writes:
FWIW: Mango still uses a custom filter, and some specific Doxygen/cpp settings
(for handling version() etc), to produce its documentation. Both are available
via the \trunk\mango\doc folder over at dsource.org



In article <d0l0nr$6re$1 digitaldaemon.com>,
=?ISO-8859-1?Q?Anders_F_Bj=F6rklund?= says...

Found out why doxygen didn't seem to support D,
the file suffix check in Doxygen 1.4.1 was flawed...

http://bugzilla.gnome.org/show_bug.cgi?id=169640

 Thanks, apparently you're the first D user that tries doxygen ;-)



With a little more effort, it shouldn't be at all
hard to make Doxygen support most of the D files.
(natively, without filtering into C++/Java first)

If you feel that you could help, then please do ?
(if nothing else, then just by running it with your
code and noting the areas that needs improvement?)

http://www.doxygen.org/

--anders
Mar 08 2005
next sibling parent reply =?ISO-8859-1?Q?Anders_F_Bj=F6rklund?= <afb algonet.se> writes:
Kris wrote:


 FWIW: Mango still uses a custom filter, and some specific Doxygen/cpp settings
 (for handling version() etc), to produce its documentation. Both are available
 via the \trunk\mango\doc folder over at dsource.org


Which dfilter are you using ? I could only find a "dfilter.exe" binary ?

Is there any source code available for it, like in D as the others... ?

--anders
Mar 08 2005
parent reply Kris <Kris_member pathlink.com> writes:
Sure ~ I'll check it in later. The filter just handles additional comment-styles
.. but it's the config file that does the version() stuff and so  on. It does
that by defining certain CPP macros to rename some D keywords.


In article <d0l3d5$ab7$1 digitaldaemon.com>,
=?ISO-8859-1?Q?Anders_F_Bj=F6rklund?= says...

Kris wrote:


 FWIW: Mango still uses a custom filter, and some specific Doxygen/cpp settings
 (for handling version() etc), to produce its documentation. Both are available
 via the \trunk\mango\doc folder over at dsource.org


Which dfilter are you using ? I could only find a "dfilter.exe" binary ?

Is there any source code available for it, like in D as the others... ?

--anders
Mar 08 2005
next sibling parent =?ISO-8859-1?Q?Anders_F_Bj=F6rklund?= <afb algonet.se> writes:
Kris wrote:


 Sure ~ I'll check it in later. The filter just handles additional
comment-styles
 .. but it's the config file that does the version() stuff and so  on. It does
 that by defining certain CPP macros to rename some D keywords.


That part I saw. I tried upgrading your Doxyfile to 1.4.1 and then
running without any filter, to see what kind of trouble we're in...


 Searching for friends...
 Searching for documented defines...
 Computing template instances...
 zsh: segmentation fault  doxygen


Oops! Seems like there are a few bug reports left to write yet :-)
For now, I think you'd do best in sticking with Doxygen 1.3.x ?


 Doxygen Release 1.3.6

 New features
   Include a patch by Hauke Duden which adds preliminary support
   for the D programming language (see http://www.digitalmars.com/d).



Constructors were simple, but debug() and version() are gonna be fun.
We probably also want to rename namespaces to modules, at some point?

And of course you could probably confuse it silly, with clever use
of alias and mixins and other features that are far from C++ / Java.


Still, it's a great tool - and Dimitri is busy adding Objective-C
support on his shiny new Mac, so what's another language then ? :-)

The class diagrams and the PDF documentation generator are awesome,
and I find the general look of the new HTML stylesheet to be great...

--anders
Mar 08 2005
prev sibling parent reply =?ISO-8859-1?Q?Anders_F_Bj=F6rklund?= <afb algonet.se> writes:
Kris wrote:


 .. but it's the config file that does the version() stuff and so  on. It does
 that by defining certain CPP macros to rename some D keywords.


PREDEFINED             = DOXYGEN_SHOULD_SKIP_THIS \

                          interface=struct

Interfaces should be able to be handled by Doxygen,
once the "D mode" is activated (and not crashing...)
They are pretty similar to Javas, which is supported.

The "missing" semicolons after certain structures
are also handle with the same "D mode", by the way.

Using "class" for version(x) probably doesn't work
too good for the "else" statements, or does it ?


James Dunne wrote:


 Also, previously unreleased, I have made my own modifications to dfilter.d to
 allow version() blocks translated into #ifdef and #elif and #endif blocks, as
 well as other minor modifications I found helpful.


// These modifications allow version (identifier) { } else { } blocks
// to be replaced with corresponding C preprocessor #ifdef blocks which
// doxygen recognizes and interprets. The identifiers are translated
// into all uppercase with a VERSION_ prefix.

This probably works better, and is closer to how D handles
versions (which should also include "debug", by the way?)
The braces are optional, but that could be added easily.


It seems like the best (ultimately) way of handling this is adding new
code to Doxygen, to make it able to handle the "version" and "debug" ?

I've added an "isD" boolean next to the Objective-C stuff, and plan to
make some use of it one day. Although I wouldn't hold my breath...

--anders
Mar 08 2005
parent reply Kris <Kris_member pathlink.com> writes:
In article <d0la4e$i4n$1 digitaldaemon.com>,
=?ISO-8859-1?Q?Anders_F_Bj=F6rklund?= says...

Kris wrote:


 .. but it's the config file that does the version() stuff and so  on. It does
 that by defining certain CPP macros to rename some D keywords.


PREDEFINED             = DOXYGEN_SHOULD_SKIP_THIS \

                          interface=struct

Interfaces should be able to be handled by Doxygen,
once the "D mode" is activated (and not crashing...)
They are pretty similar to Javas, which is supported.

The "missing" semicolons after certain structures
are also handle with the same "D mode", by the way.

Using "class" for version(x) probably doesn't work
too good for the "else" statements, or does it ?


Right! It wasn't meant to be 'correct' :-D

I just fussed around with a bunch of different approaches until the Mango
documentation started to actually include what it was supposed to. Doxygen is
very useful, but there are too many subtle differences going from Java/C++ to D
for it to do a primo job. I'll be quite happy when there are better alternatives
:-)
Mar 08 2005
next sibling parent reply =?ISO-8859-1?Q?Anders_F_Bj=F6rklund?= <afb algonet.se> writes:
Kris wrote:


 I just fussed around with a bunch of different approaches until the Mango
 documentation started to actually include what it was supposed to. Doxygen is
 very useful, but there are too many subtle differences going from Java/C++ to D
 for it to do a primo job. I'll be quite happy when there are better
alternatives
 :-)


You mean like "ddoc" or leds html-generator ?
http://dsource.org/projects/ddoc/
http://leds.sourceforge.net/


It's not that there are not alternatives,
see e.g. http://www.doxygen.org/links.html

Just that I find Doxygen to be one of the best.
(have used it for documenting C projects before)


It's really too bad that the D specification doesn't
discuss inline documentation tags ? They're useful...

I use JavaDoc(-ish) tags, because I'm used to them.
But I do find the /// and ///< short forms excellent.

--anders
Mar 08 2005
parent J C Calvarese <jcc7 cox.net> writes:
Anders F Björklund wrote:

 Kris wrote:


...

 for it to do a primo job. I'll be quite happy when there are better 
 alternatives
 :-)


 
 
 You mean like "ddoc" or leds html-generator ?
 http://dsource.org/projects/ddoc/


Not to malign the "ddoc" effort, but it hasn't released any binary or 
even source yet. At least, all I can find in the repository 
(http://svn.dsource.org/svn/projects/ddoc/) is a license.

I'm guessing Doxygen has a lot more practical value if you're 
documenting a project today. :)

-- 
Justin (a/k/a jcc7)
http://jcc_7.tripod.com/d/
Mar 08 2005
prev sibling parent reply Brad Anderson <brad dsource.dot.org> writes:
Kris wrote:

 In article <d0la4e$i4n$1 digitaldaemon.com>,
 =?ISO-8859-1?Q?Anders_F_Bj=F6rklund?= says...
 

Kris wrote:



.. but it's the config file that does the version() stuff and so  on. It does
that by defining certain CPP macros to rename some D keywords.


PREDEFINED             = DOXYGEN_SHOULD_SKIP_THIS \

                         interface=struct

Interfaces should be able to be handled by Doxygen,
once the "D mode" is activated (and not crashing...)
They are pretty similar to Javas, which is supported.

The "missing" semicolons after certain structures
are also handle with the same "D mode", by the way.

Using "class" for version(x) probably doesn't work
too good for the "else" statements, or does it ?


 
 
 Right! It wasn't meant to be 'correct' :-D
 
 I just fussed around with a bunch of different approaches until the Mango
 documentation started to actually include what it was supposed to. Doxygen is
 very useful, but there are too many subtle differences going from Java/C++ to D
 for it to do a primo job. I'll be quite happy when there are better
alternatives
 :-)
 
 


And I can add a post-commit-hook on SVN (for releases only?) that will 
do the Doxygen processing on the dsource.org server instead of on your 
local machine.  Then you don't have to check in the docs as well, and I 
could move the files over to your public site (i.e. 
http://mango.dsource.org)

Or do you still want the control down on your local development machine?

BA
Mar 08 2005
parent reply Kris <Kris_member pathlink.com> writes:
In article <d0lbld$jq5$1 digitaldaemon.com>, Brad Anderson says...

Kris wrote:

 In article <d0la4e$i4n$1 digitaldaemon.com>,
 =?ISO-8859-1?Q?Anders_F_Bj=F6rklund?= says...
 

Kris wrote:



.. but it's the config file that does the version() stuff and so  on. It does
that by defining certain CPP macros to rename some D keywords.


PREDEFINED             = DOXYGEN_SHOULD_SKIP_THIS \

                         interface=struct

Interfaces should be able to be handled by Doxygen,
once the "D mode" is activated (and not crashing...)
They are pretty similar to Javas, which is supported.

The "missing" semicolons after certain structures
are also handle with the same "D mode", by the way.

Using "class" for version(x) probably doesn't work
too good for the "else" statements, or does it ?


 
 
 Right! It wasn't meant to be 'correct' :-D
 
 I just fussed around with a bunch of different approaches until the Mango
 documentation started to actually include what it was supposed to. Doxygen is
 very useful, but there are too many subtle differences going from Java/C++ to D
 for it to do a primo job. I'll be quite happy when there are better
alternatives
 :-)
 
 


And I can add a post-commit-hook on SVN (for releases only?) that will 
do the Doxygen processing on the dsource.org server instead of on your 
local machine.  Then you don't have to check in the docs as well, and I 
could move the files over to your public site (i.e. 
http://mango.dsource.org)

Or do you still want the control down on your local development machine?

BA



That would be awesome, Brad! 

How would one trigger it? Via the 'admin' page perhaps?
Mar 08 2005
parent Brad Anderson <brad dsource.dot.org> writes:
Kris wrote:

And I can add a post-commit-hook on SVN (for releases only?) that will 
do the Doxygen processing on the dsource.org server instead of on your 
local machine.  Then you don't have to check in the docs as well, and I 
could move the files over to your public site (i.e. 
http://mango.dsource.org)

Or do you still want the control down on your local development machine?

BA


 
 
 
 That would be awesome, Brad! 
 
 How would one trigger it? Via the 'admin' page perhaps?
 


Maybe the admin pages as you suggest.  In an extreme case, it can be 
triggered for every commit.  I'll have to think about it, and how to do 
it for releases only.  Something like, when you tag a release in /tags.
Mar 08 2005
prev sibling parent reply James Dunne <jdunne4 bradley.edu> writes:
Also, previously unreleased, I have made my own modifications to dfilter.d to
allow version() blocks translated into #ifdef and #elif and #endif blocks, as
well as other minor modifications I found helpful.  I'll post it in the bindings
project on dsource.org.  I still think they should have a code-snippets section
for shared D modules not big enough to warrant the need for a full SVN
repository.

In article <d0l2l7$9g0$1 digitaldaemon.com>, Kris says...

FWIW: Mango still uses a custom filter, and some specific Doxygen/cpp settings
(for handling version() etc), to produce its documentation. Both are available
via the \trunk\mango\doc folder over at dsource.org


Regards,
James Dunne
Mar 08 2005
next sibling parent reply =?ISO-8859-1?Q?Anders_F_Bj=F6rklund?= <afb algonet.se> writes:
James Dunne wrote:


 Also, previously unreleased, I have made my own modifications to dfilter.d to
 allow version() blocks translated into #ifdef and #elif and #endif blocks, as
 well as other minor modifications I found helpful. 


I did a quick patch to support D constructors and deathtractors:
http://bugzilla.gnome.org/show_bug.cgi?id=169641


 I'll post it in the bindings
 project on dsource.org.  I still think they should have a code-snippets section
 for shared D modules not big enough to warrant the need for a full SVN
 repository.


Found it, at:
http://svn.dsource.org/svn/projects/bindings/trunk/dfilter.d

--anders
Mar 08 2005
parent reply James Dunne <jdunne4 bradley.edu> writes:
In article <d0l8u4$gqg$1 digitaldaemon.com>,
=?ISO-8859-1?Q?Anders_F_Bj=F6rklund?= says...

James Dunne wrote:


 Also, previously unreleased, I have made my own modifications to dfilter.d to
 allow version() blocks translated into #ifdef and #elif and #endif blocks, as
 well as other minor modifications I found helpful. 


I did a quick patch to support D constructors and deathtractors:
http://bugzilla.gnome.org/show_bug.cgi?id=169641


Cool!  doxygen code-patches are probably much more useful/better than
pre-filtering code.


 I'll post it in the bindings
 project on dsource.org.  I still think they should have a code-snippets section
 for shared D modules not big enough to warrant the need for a full SVN
 repository.


Found it, at:
http://svn.dsource.org/svn/projects/bindings/trunk/dfilter.d

--anders


That's where she be.

I was workin on a school independent study project and needed to hack up a
quickie presentation for my prof.  doxygen did the trick with dfilter alright.
I was too lazy to actually d/l a copy of the doxygen source and modify it, then
recompile it myself.

Also, am I the only one who finds doxygen's use of external DOT tools to
generate graphs extremely and unreasonably SLOW?  Maybe it's just me, but
calling external programs within a program doesn't seem to be optimal.

Regards,
James Dunne
Mar 08 2005
parent =?ISO-8859-1?Q?Anders_F_Bj=F6rklund?= <afb algonet.se> writes:
James Dunne wrote:


 I was too lazy to actually d/l a copy of the doxygen source and modify it, then
 recompile it myself.


I'm using RPM to handle builds, using pristine sources and patch files.
This works good, both for version updates and for hacking new stuff in.

I can recommend it... (or some other similar* automated build method ?)
As a bonus you get reproducible builds and ready-made binary packages.

--anders

* RPM, Deb, Fink, DarwinPorts, Ports, Gentoo, whatever works for you.
Mar 08 2005
prev sibling parent reply Stewart Gordon <smjg_1998 yahoo.com> writes:
James Dunne wrote:

 Also, previously unreleased, I have made my own modifications to dfilter.d to
 allow version() blocks translated into #ifdef and #elif and #endif blocks, as
 well as other minor modifications I found helpful.


This has diverged quite a bit from the version I've been maintaining.

http://www.digitalmars.com/drn-bin/wwwnews?digitalmars.D/7994

My (not yet implemented) thought on version blocks was that Dfilter 
should actually filter them, rather than turning them into C 
preprocessor commands.  Not only does this idea keep all filtering in 
one place, but having what gets filtered out only dealt with once seems 
more efficient.

Whatever we do here, we ought to bring versions together on Dsource. 
Can you remember what your "other minor modifications" do?


 // original author unknown/forgotten by me (feel free to give credit)


Hauke Duden was maintaining it for a while, but hasn't been seen since 
last July.  Don't know if Hauke was the original author though....

Stewart.

-- 
My e-mail is valid but not my primary mailbox.  Please keep replies on 
the 'group where everyone may benefit.
Mar 09 2005
next sibling parent =?ISO-8859-1?Q?Anders_F_Bj=F6rklund?= <afb algonet.se> writes:
Stewart Gordon wrote:


 My (not yet implemented) thought on version blocks was that Dfilter 
 should actually filter them, rather than turning them into C 
 preprocessor commands.  Not only does this idea keep all filtering in 
 one place, but having what gets filtered out only dealt with once seems 
 more efficient.


That might turn out simpler to do than add support for D
conditional compilation to the Doxygen pre-preprocessor... :-)


 Whatever we do here, we ought to bring versions together on Dsource.


Perhaps even start up a "dfilter" or "ddoxygen" Dsource project for it ?
I put some links on http://www.prowiki.org/wiki4d/wiki.cgi?DoxygenIssues

--anders
Mar 09 2005
prev sibling parent reply J C Calvarese <jcc7 cox.net> writes:
In article <d0nag9$2noh$1 digitaldaemon.com>, Stewart Gordon says...

James Dunne wrote:

 // original author unknown/forgotten by me (feel free to give credit)


Hauke Duden was maintaining it for a while, but hasn't been seen since 
last July.  Don't know if Hauke was the original author though....


I belive that Burton Radons wrote a dfilter (or at least modified someone else's
code) way back when for his Dig library (http://www.opend.org/dig/index.html). I
don't know if the current filters are related to his efforts though. It should
have looked something like this:
http://svn.dsource.org/svn/projects/undig/trunk/net/BurtonRadons/digc/dfilter.d
(and I'm sure that any dig edition of dfilter is going to be obsolete).

jcc7
Mar 09 2005
parent reply Stewart Gordon <smjg_1998 yahoo.com> writes:
J C Calvarese wrote:

 In article <d0nag9$2noh$1 digitaldaemon.com>, Stewart Gordon says...
 

James Dunne wrote:


// original author unknown/forgotten by me (feel free to give credit)


Hauke Duden was maintaining it for a while, but hasn't been seen since 
last July.  Don't know if Hauke was the original author though....


 
 
 I belive that Burton Radons wrote a dfilter (or at least modified someone
else's
 code) way back when for his Dig library (http://www.opend.org/dig/index.html).
I
 don't know if the current filters are related to his efforts though. It should
 have looked something like this:
 http://svn.dsource.org/svn/projects/undig/trunk/net/BurtonRadons/digc/dfilter.d
 (and I'm sure that any dig edition of dfilter is going to be obsolete).


Burton claimed he managed without a filter.  How, I can't imagine.

http://www.digitalmars.com/drn-bin/wwwnews?digitalmars.D/11272

Stewart.

-- 
My e-mail is valid but not my primary mailbox.  Please keep replies on 
the 'group where everyone may benefit.
Mar 09 2005
parent J C Calvarese <jcc7 cox.net> writes:
Stewart Gordon wrote:

 J C Calvarese wrote:
 

 In article <d0nag9$2noh$1 digitaldaemon.com>, Stewart Gordon says...


 James Dunne wrote:


 // original author unknown/forgotten by me (feel free to give credit)



 Hauke Duden was maintaining it for a while, but hasn't been seen 
 since last July.  Don't know if Hauke was the original author though....




 I belive that Burton Radons wrote a dfilter (or at least modified 
 someone else's
 code) way back when for his Dig library 
 (http://www.opend.org/dig/index.html). I
 don't know if the current filters are related to his efforts though. 
 It should
 have looked something like this:
 http://svn.dsource.org/svn/projects/undig/trunk/net/BurtonR
dons/digc/dfilter.d 

 (and I'm sure that any dig edition of dfilter is going to be obsolete).


 
 
 Burton claimed he managed without a filter.  How, I can't imagine.
 
 http://www.digitalmars.com/drn-bin/wwwnews?digitalmars.D/11272
 
 Stewart.


Hmmm. So he did.

Perhaps he wrote a filter when he was working on Dig. Later, perhaps, he 
thought that doxygen was analyzing his code well enough. I don't know.

Or maybe someone else added dfilter to the undig repository. It's a very 
mysterious situation. ;)

Maybe Burton will post another message sometime and clear it up for us...

-- 
Justin (a/k/a jcc7)
http://jcc_7.tripod.com/d/
Mar 12 2005