Browse haiku: This Month's Archive • Main Archive Page • Related posts • Previous by Date • Next by Date

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

From: Simon Kennedy <stonewolfsoft@xxxxxxxxxxx>
To: openbeos@xxxxxxxxxxxxx
Date: Sat, 03 Mar 2007 10:06:49 +0000

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 musthave been hibernating at that time :-)), but, well, decisions are made tobe unmade. ;-)
Note that I pretty much don't mind what format to use for otherdocumentation (end user, whatever ...), but for API docs it should beDoxygen, IMHO.
CU, Ingo

Hi

As a quick introduction I'm the person who has produced the Be and Haikunewsletters you can find on BeBits for which I used the Docbooktoolchain and for these types of documents Docbook is relatively easy touse as the vast majority of the text is just text with no semanticinformation.

Now, the newsletters were only a small diversion from my attempt torecreate 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 Docbook5 with its namespaces makes it even worse.)

Having looked at Doxygen a while ago it seemed to be the ideal solutionfor documenting the source for Haiku. However I've come to like the waythe BeBook is laid out, less dry and formal than Doxygen documentationseems to be. Doxygen does however produce some nice extras such as classhierarchy diagrams.

Doxygen also has one thing which may be used to in the future (as Idon't think anybody on the www has currently built a complete solutioni.e. it does not exist yet) to produce a documentation toolchain andthat is, and Ingo might not like this, XML output. This would allow fora set of XSLT templates to transform the Doxygen output into Docbook andthen you would gain the best of both worlds. Simple markup and prettyoutput.

Taking the above into account I can see no other option at the currenttime than Doxygen. The task of documenting the Haiku API will take along time and other solutions may appear before we have finished thetask and at that time we may change to this method, but for now Doxygenseems the correct solution to the problem. It also should be possible totransform 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 youcan see it here


http://www.sffjunkie.co.uk/beos/BeBook/index.html

I have currently completed all except the Media, Midi, Network andOpenGL 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 Magazinehttp://uk.docs.yahoo.com/nowyoucan.html

Follow-Ups:

[openbeos] Re: API documentation (part III?)
From: Ralf Schülke

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

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

References:
- [openbeos] API documentation (part III?)
  - From: Niels Reedijk
- [openbeos] Re: API documentation (part III?)
  - From: Ingo Weinhold

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

Other related posts: