[openbeos] Re: First draft of the API documentation guidelines

Ingo Weinhold <bonefish@xxxxxxxxxxxxxxx> wrote:
> On 2007-03-19 at 11:04:37 [+0100], Niels Reedijk <
> niels.reedijk@xxxxxxxxx> 
> wrote:
> > I just commited the first draft of the API documentation 
> > guidelines,
> > to start a discussion.
> 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.

Where have you been when we discussed this in the first place? :-)
Anyway, I think that only internal documentation should be put into the 
actual source files - end user documentation should usually be lengthy. 
If we get warnings for missing docs, I don't see an advantage of having 
the docs with the code, especially since our API is mostly stable and 
not that much of a moving target.

Bye,
   Axel.

Other related posts: