[openbeos] Re: First draft of the API documentation guidelines
- From: "Niels Reedijk" <niels.reedijk@xxxxxxxxx>
- To: openbeos@xxxxxxxxxxxxx
- Date: Thu, 22 Mar 2007 17:09:39 +0100
Hi,
Okay, it seems that there is one major issue that might need to be
resolved before some effort can be made to structurally start
documenting. The issue is where to put the documentation.
I said before that it wasn't my call, but since I'm planning to do
some documenting, I'd like to add my view to it.
My plan is basically to do the following (for R1). I want to ask the
developers of the classes to write a bare-bones documentation of their
classes. Then I'd like to go over the documentation with a team of
documenters, flesh out the descriptions, add some examples, etcetera.
This is a good approach because:
a) It will create an uniform documentation because it is written by
people that work intensively on this, since
i) not all developers will have a good talent of writing
documentation (no offence)
ii) not all developers will have English as a first language
b) It will keep the developers 'free' from worrying too much about
documentation.
I suggest we do the documentations in different files, because:
a) It's likely to have many iterations, improvements. Revision control
for .cpp files is revision control for the source, and not for every
spelling mistake fixed. you don't want to look through a larger number
of revisions to see when you might have introduced a bug.
b) Some of the documentation might be done by people with less
knowledge of C++, or subversion, or diff, or any combination of these.
To keep the tree from busting, let's prevent the possibility that it
actually can be broken by doing the documentation in different files
(yes, I know, there are precautions, but we all have mistakes that
happen in oversight).
c) Documentation should document header files, which are likely to
contain more information than source files. If I add a new inline
method, where should I document it? Separate file or in the source
file? No matter what you choose, you will always end up having to
search for it. A separate file is a separate file.
As I said before, Doxygen's parser still checks for missing methods,
wrong parameters, invalid function declarations in the .dox files.
That won't change. I just want to prevent a mess of different
locations of documentation, for both coders and documenters. While the
argument for keeping it in the source is compelling, namely that with
api changes the coder will most likely update the docs, I think we can
put in place a mechanism that will prevent that sort of stuff.
Actually ,that's why the header of .dox files should contain the
revision numbers of the files it was written against. And post R1,
we'll see about that then (something like an obligatory keyword in the
log message in case of APi changes, or something like that). Point is,
we're not at R1 yet, and I would like to play around with the
documentation a bit, without getting into other peoples water.
I guess that it might be worth discussing on this single issue, since
it affects the process of documenting fundamentally. After that, I
hope we can start doing some work. I received emails from two people
that are willing to invest time in the API documentation, and I assume
it's a waste not to use their offer.
Kind regards,
Niels
Other related posts:
