[openbeos] Re: First draft of the API documentation guidelines
- From: "Niels Reedijk" <niels.reedijk@xxxxxxxxx>
- To: openbeos@xxxxxxxxxxxxx
- Date: Wed, 21 Mar 2007 15:18:08 +0100
Thanks for all the feedback. I'm going to try to respond to points of
critique on the guide in this mail.
2007/3/20, Axel Dörfler <axeld@xxxxxxxxxxxxxxxx>:
But I also have a few remarks:
1) is there any need to deviate from the standard license header that
looks like this:
/*
* Copyright 2007, Haiku ...
* Distributed ...
*
* Authors:
* ...
*/
My thoughts were that it should look different from the doxygen
blocks. Alas, I have no problem with this format, and I think it's a
good idea to adopt this one.
Also, I think the "Corresponds To" is redundant, and already determined
by the name of the file and its location
The corresponds is more to keep track of changes that might happen to
the code. In case some changes are made, between releases, the API
docs can be kept up to date by doing SVN diffs between the revision
the docs were written for and the new revision. (Of course this
doesn't cover all changes, for example in servers, but at least it
works like a manual check to keep the docs up to date).
2) Is there any need to enforce mirroring the header files? I mean, is
it a doxygen restriction or is that something you think would make more
sense? At least as long as we get warnings for missing documentation,
the order shouldn't be important (even though it makes sense to follow
the header, there might be useful deviations for grouping, ie. if a
virtual was added and is therefore not declared in the group of
functions it would be expected).
Well, the reason is that I feel it is easier to keep the docs up to
date in case of changes in the headers, however, your argument for
grouping is quite strong. Perhaps it should be rephrased to something
like 'Mirror the order of the headers, except when you need to group
members." I had a thought that it might be a good idea to group
headers (and source), but I just realized that this is not always
possible due to binary incompatibility if virtual members move
(right?).
2007/3/20, Ingo Weinhold <bonefish@xxxxxxxxxxxxxxx>:
Personally I'm very much in favor of inline documentation (though not in
the headers for obvious reasons). If for some reason a documentation
becomes lengthy I don't have a problem with moving it to a separate file,
but in general I'd prefer it to stay with the implementation.
There are arguments for and against inline documentation, and I don't
think it's my call. I'm fine with doing the docs in separate files,
I'll also be fine with doing docs inline in source. The only thing is
that creating member groups in source files might prove to be a bit
more dificult, since you either fysically need to rearrange the
members, or you need to put the docs in another place. But that's not
my call to make. I do think that we should choose one or the other. I
don't want mixins of some kits being documented inline and some being
done in separate files, or even that some kits have it all.
(There is one argument why I really like to have separate files
though, and I mention this one from experience with my investigations
so far, I feel that it's best to mirror header files in separate dox
files as much as possible, because headers contain all the information
(enums, typedefs, etc.))
2007/3/20, Tyler Akidau <haiku@xxxxxxxxxx>:
On 3/20/07, Tyler Akidau <haiku@xxxxxxxxxx> wrote:
Some minor typos I forgot to mention:
"Doxygen, the tool that we use to generate the marked up documentation
with,"
I don't think the word "with" is entirely correct or necessary in this
sentence:
No, it an mistake indeed, it's a Dutchism combined with a logic error.
Fixed on my hard drive
"Every documentation file will begin with the header block. It's basically
a copyright block, with a reference to the author and with the revision
against which the documentaton was written."
Should that say "reference to the author(s)"?
Fixed.
Niels
Other related posts:
