[openbeos] Re: First draft of the API documentation guidelines
- From: "Axel Dörfler" <axeld@xxxxxxxxxxxxxxxx>
- To: openbeos@xxxxxxxxxxxxx
- Date: Tue, 20 Mar 2007 02:06:46 +0100 CET
Hi Niels,
"Niels Reedijk" <niels.reedijk@xxxxxxxxx> wrote:
> I just commited the first draft of the API documentation guidelines,
> to start a discussion. Ideally, I'd like to form a subgroup (or team)
> to discuss this on a separate mailing list or a web forum (though I
> prefer mail).
First of all, thanks for doing all the work :-)
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:
* ...
*/
?
Also, I think the "Corresponds To" is redundant, and already determined
by the name of the file and its location
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).
I didn't get much further with reading, yet :-)
Bye,
Axel.
Other related posts:
