[interfacekit] [Fwd: Re: Application Kit Tech Lead]



-------- Original Message --------
Subject: Re: Application Kit Tech Lead
Date: Tue, 13 Nov 2001 16:24:49 +0100
From: "Ithamar R. Adema" <ithamar@xxxxxxxxx>
To: erik@xxxxxxxxxxxxxx

>I'm glad you brought this stuff up (formatting interface specs) because 
>I'm currently wrestling with this myself.  I've been reimplementing 
>BArchivable & Co. to act as an example, but I've gotten sort of stuck on 
>exactly where the dividing line between functional/interface spec and 
>technical spec is and how it all relates to a) making it relatively easy 
>to use what the BeBook already provides, b) making it relatively easy to 
>create/maintain the OBOS version of the BeBook and c) making it easy on 
>the devs so they'll actually complete and maintain the docs.  So!  I'm 
>happy to hear whatever ideas you have concerning this.  My bullet-items 
>thus far:
>
>* Keep as much of the documentation in source as possible (as opposed to 
>stand-alone documents)
>* Re-use as much of the current BeBook material as possible
>* Make extraction of documentation as painless and automatic as possible
>

Ok, here we go: 

My suggestion is to use doxygen. It is a neat piece of software, runs 
on BeOS, Windows, Linux, etc, and supports both QT and JavaDoc style 
comments for generating documentation from. To boot, it supports 
Postscript, TeX, HTML, and some other output format, so whether we want 
to generate another "lovely-html" BeBook, or something for print, we 
can use the same source :)

I've mostly finished the print_server now. There are some things left 
to do, but most of it is working :) I can use it to print, and it works 
with the existing libbe.so and Printers preference panel :) I've 
documented the code using the BeIDE addon that is in CVS, but going to 
update the comments to doxygen style. I also want to include my "R&D" 
text files, so I'll see how that can be done best using doxygen.

It looks like that should be pretty easy to do in a day or so, so I'll 
start on it straight away. Doxygen allows comments to be placed in 
headers, or source or both, so it is sufficient for your preference 
(and mine too, I want them in the sourcefiles too).

Reusing BeBook material is a tricky thing, we come back to our initial 
"will the laywers let us do this" thing. BeBook content is property of 
Be, Inc I'm afraid..... But ok, I'm not to bothered about that, can't 
imagine Palm sueing us over that :)


>Ideally, Dan Reinhold could do a cvs update, run an extraction tool, and 
>publish the latest version of the docs.  Something that takes 10 or 15 
>minutes, so we can have up-to-date docs once a week (at least).  If we 
>get something nice worked out, we could pass it along to the entire team 
>as a proposed standard for the whole project.
>

Extraction of docs could be part of the build process, just another 
target in the makefiles :) That's what's done most and I think that 
would be pretty usefull....
Doxygen could even be run within the "build farm" thing on sourceforge, 
so it could generate new docs for use on the website every night 
automagicly if we want :)

>BTW, in addition to my BArchivable work, I have a ton of stuff from 
>Frans van Nispen (sp?) just waiting to get checked in -- I'm holding off 
>because I want to be able to assign the documentation work as soon as 
>it's in, which I can't do until the format is worked out =P.
>

This should be done pretty soon, I used doxygen before, so creating 
something usefull shouldn't take too long :)

>Glad you like the website; once we get this documentation issue hammered 
>out, I'm going to finish up the tools for managing the site content and 
>then convince Dan that he should let us generate our own content for the 
>IK team page. =)
>

Sounds like a great plan :) I think I might do something simular when 
the print_kit is released......



So much interesting work to be done and so little time :)

Regards,

Ithamar.

PS: I'm evangelising on BeShare now-and-then, sometimes showing the 
link to the website, hope you don't mind :)

Other related posts: