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....

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

as well as a much more up-to-date version of dfilter....

http://www.digitalmars.com/drn-bin/wwwnews?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....
 http://www.digitalmars.com/drn-bin/wwwnews?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....
 
 http://www.digitalmars.com/drn-bin/wwwnews?digitalmars.D/11272
 
 as well as a much more up-to-date version of dfilter....
 
 http://www.digitalmars.com/drn-bin/wwwnews?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