Thread overview | |||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|
|
March 01, 2005 Doxygen and Phobos | ||||
---|---|---|---|---|
| ||||
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... |
March 01, 2005 Re: Doxygen and Phobos | ||||
---|---|---|---|---|
| ||||
Posted in reply to Anders F Björklund | 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
|
March 02, 2005 Re: Doxygen and Phobos | ||||
---|---|---|---|---|
| ||||
Posted in reply to Carlos Santander B. | 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
|
March 02, 2005 Re: Doxygen and Phobos | ||||
---|---|---|---|---|
| ||||
Posted in reply to Anders F Björklund | 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 |
March 02, 2005 Re: Doxygen and Phobos | ||||
---|---|---|---|---|
| ||||
Posted in reply to Carlos Santander B. | 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 |
March 02, 2005 Re: Doxygen and Phobos | ||||
---|---|---|---|---|
| ||||
Posted in reply to nail | 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.
|
March 02, 2005 Re: Doxygen and Phobos | ||||
---|---|---|---|---|
| ||||
Posted in reply to Carlos Santander B. | 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. |
March 02, 2005 Re: Doxygen and Phobos | ||||
---|---|---|---|---|
| ||||
Posted in reply to Stewart Gordon | 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 |
March 02, 2005 Re: Doxygen and Phobos | ||||
---|---|---|---|---|
| ||||
Posted in reply to Stewart Gordon | > 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 |
Copyright © 1999-2021 by the D Language Foundation