[openbeos] Re: API documentation (part III?)

Ingo Weinhold wrote:
I've made no secret of my dislike for using Docbook for API documentation. I somehow missed the discussion and the decision to switch to it (I must have been hibernating at that time :-)), but, well, decisions are made to be unmade. ;-)
Note that I pretty much don't mind what format to use for other documentation (end user, whatever ...), but for API docs it should be Doxygen, IMHO. 

CU, Ingo


Hi
As a quick introduction I'm the person who has produced the Be and Haiku newsletters you can find on BeBits for which I used the Docbook toolchain and for these types of documents Docbook is relatively easy to use as the vast majority of the text is just text with no semantic information.
Now, the newsletters were only a small diversion from my attempt to recreate the BeBook in Docbook, which is a different animal altogether. Almost every other word requires an xml element to be wrapped around it, with the result that it's rather verbose (and the conversion to Docbook 5 with its namespaces makes it even worse.)
Having looked at Doxygen a while ago it seemed to be the ideal solution for documenting the source for Haiku. However I've come to like the way the BeBook is laid out, less dry and formal than Doxygen documentation seems to be. Doxygen does however produce some nice extras such as class hierarchy diagrams.
Doxygen also has one thing which may be used to in the future (as I don't think anybody on the www has currently built a complete solution i.e. it does not exist yet) to produce a documentation toolchain and that is, and Ingo might not like this, XML output. This would allow for a set of XSLT templates to transform the Doxygen output into Docbook and then you would gain the best of both worlds. Simple markup and pretty output.
Taking the above into account I can see no other option at the current time than Doxygen. The task of documenting the Haiku API will take a long time and other solutions may appear before we have finished the task and at that time we may change to this method, but for now Doxygen seems the correct solution to the problem. It also should be possible to transform the Doxygen markup to another form with little or no cost (Assuming the Doxygen team produce the method for us :-) .
If you want to see where I have got to with recreating the BeBook you can see it here 

http://www.sffjunkie.co.uk/beos/BeBook/index.html
I have currently completed all except the Media, Midi, Network and OpenGL kits with the Media kit being half done. 

If you want to download the current state you can find it here

http://www.sffjunkie.co.uk/beos/files/BeBook.zip

and as a example of what the BeBook looks like in Docbook 5

http://www.sffjunkie.co.uk/beos/files/BApplication.xml

Regards
Simon Kennedy
___________________________________________________________ All new Yahoo! Mail "The new Interface is stunning in its simplicity and ease of use." - PC Magazine http://uk.docs.yahoo.com/nowyoucan.html

Other related posts: