www.digitalmars.com         C & C++   DMDScript  

digitalmars.D - Doxygen and Phobos

reply =?ISO-8859-1?Q?Anders_F_Bj=F6rklund?= <afb algonet.se> writes:
I know there was some talk about adding
documentation to Phobos (source code)
using Doxygen, but not what happened ?


Using the "dfilter" program and the
(http://www.algonet.se/~afb/d/dfilter.d)
regular vanilla Doxygen installation
(http://www.doxygen.org/download.html)
it is not hard to add inline "JavaDoc"
style documentation to all D modules...

Here's one example, for Phobos' object.d:
http://www.algonet.se/~afb/d/doxygen/html/


I just took the regular object.d (with some
GDC patches, but) and added some documentation:
http://www.algonet.se/~afb/d/doxygen/object.diff

I then made a Makefile and a Doxyfile, to avoid
(http://www.algonet.se/~afb/d/doxygen/Makefile,
  http://www.algonet.se/~afb/d/doxygen/Doxyfile)
having to type the commands more than once -
and in the end it was just to run "make docs"...

The "dfilter" program preprocesses the special
D constructs so that the end result looks more
like C/C++, which Doxygen knows how to handle:
http://www.algonet.se/~afb/d/doxygen/object.d.txt

By installing LaTeX and ps2pdf (extra) one can even
make Doxygen generate PDF versions, without problems:
http://www.algonet.se/~afb/d/doxygen/pdf.zip
(seem to have messed up the font in that one, but)

The rest of the example files are available at:
http://www.algonet.se/~afb/d/doxygen/


There is not much that needs to be added to the code,
and it offers great benefit in the end. A lot like
what adding Unit Tests and Asserts/Contracts does...

I think that it should be made a part of standard D ?
Naturally someone will want to make their own tool, :-P
but until "dmake" and "ddoc": Make and Doxygen works.


What do you say ? Any volunteers to do the rest ? ;-)

Some information can be taken from:
http://www.digitalmars.com/d/phobos.html
http://www.prowiki.org/wiki4d/wiki.cgi?Phobos
http://www.quit-clan.de/docwiki/view.php?pageid=19

--anders


PS.  I used the "JavaDoc style", being used to Java.
      There is also a "Qt Style" available in Doxygen.
      See manual; http://www.doxygen.org/docblocks.html

PPS. Doxygen still needs some work to support all of D,
      and could probably need a more specific "front end"
      instead of using a filter and the C++ documentor...
Mar 01 2005
parent reply "Carlos Santander B." <csantander619 gmail.com> writes:
Anders F Björklund wrote:
 PPS. Doxygen still needs some work to support all of D,
      and could probably need a more specific "front end"
      instead of using a filter and the C++ documentor...

For a number of versions now, Doxygen has D support without the need of a filter. I don't think its support is too bad. _______________________ Carlos Santander Bernal
Mar 01 2005
next sibling parent reply =?ISO-8859-1?Q?Anders_F_Bj=F6rklund?= <afb algonet.se> writes:
Carlos Santander B. wrote:

 PPS. Doxygen still needs some work to support all of D,
      and could probably need a more specific "front end"
      instead of using a filter and the C++ documentor...

For a number of versions now, Doxygen has D support without the need of a filter. I don't think its support is too bad.

Really? I found Doxygen 1.4.1 to choke on version { } and a few other such similar D constructs. But if it can get by without the filter, so much the better... Then it's just the documentation that is left to write. :-) --anders
Mar 01 2005
parent reply "Carlos Santander B." <csantander619 gmail.com> writes:
Anders F Björklund wrote:
 Really? I found Doxygen 1.4.1 to choke on version { }
 and a few other such similar D constructs. But if it
 can get by without the filter, so much the better...
 

Then, I guess, it needs more work.
 Then it's just the documentation that is left to write. :-)
 
 --anders

_______________________ Carlos Santander Bernal
Mar 01 2005
parent reply nail <nail_member pathlink.com> writes:
All we need for full support of doxygen is just to modify src/scanner.l in doxy
src. Explore 6K lines of code, modify some of them, mere trifle. Are any
enthusiasts here? :)

Victor Nakoryakov
nail-mail<at>mail<dot>ru
Mar 02 2005
parent Bastiaan Veelo <Bastiaan.N.Veelo ntnu.no> writes:
nail wrote:
 All we need for full support of doxygen is just to modify src/scanner.l in doxy
 src. Explore 6K lines of code, modify some of them, mere trifle. Are any
 enthusiasts here? :)
 
 Victor Nakoryakov
 nail-mail<at>mail<dot>ru

A while back, Ant was working on a direct Doxygen alternative. Since D is easier to parse than C++, it is probably a good idea to drop C++ support altogether. Someone should give Ant's tool a try. (Sorry, I'm tied up at the moment...) Bastiaan.
Mar 02 2005
prev sibling parent reply Stewart Gordon <smjg_1998 yahoo.com> writes:
Carlos Santander B. wrote:
 Anders F Björklund wrote:
 
 PPS. Doxygen still needs some work to support all of D,
      and could probably need a more specific "front end"
      instead of using a filter and the C++ documentor...

For a number of versions now, Doxygen has D support without the need of a filter. I don't think its support is too bad.

I'm still on 1.3.7, but ought to upgrade soon. As I look now, it still claims it merely supports D "to some extent". I posted a list of Doxygen's failings a while back.... digitalmars.D/11272 as well as a much more up-to-date version of dfilter.... digitalmars.D/7994 Stewart. -- My e-mail is valid but not my primary mailbox. Please keep replies on the 'group where everyone may benefit.
Mar 02 2005
next sibling parent =?ISO-8859-1?Q?Anders_F_Bj=F6rklund?= <afb algonet.se> writes:
Stewart Gordon wrote:

 I'm still on 1.3.7, but ought to upgrade soon.  As I look now, it still 
 claims it merely supports D "to some extent".

Yeah, D is listed down there with PHP or something...
 as well as a much more up-to-date version of dfilter....
 digitalmars.D/7994

Thanks for posting this new version, but it does seem to eat my initial doc-comment - where I had put the mainpage ? Either way, it works "good enough" for now. (Like Make or so) Even if it does require workarounds, especially for e.g. Mango and other big libraries using lots of new D features. But adding some kind of documentation generator to the list of "recommended practices" for D would not hurt, I think... --anders
Mar 02 2005
prev sibling parent Paul Bonser <misterpib gmail.com> writes:
 I'm still on 1.3.7, but ought to upgrade soon.  As I look now, it still 
 claims it merely supports D "to some extent".
 
 I posted a list of Doxygen's failings a while back....
 
 digitalmars.D/11272
 
 as well as a much more up-to-date version of dfilter....
 
 digitalmars.D/7994
 
 Stewart.
 

And by "to some extent" they mean "to the extent which it looks like C++" -- -PIB -- "C++ also supports the notion of *friends*: cooperative classes that are permitted to see each other's private parts." - Grady Booch
Mar 02 2005