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

On 2007-03-20 at 17:02:08 [+0100], Axel Dörfler <axeld@xxxxxxxxxxxxxxxx> 
wrote:
> 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? :-)

Hibernating? :-)

> Anyway, I think that only internal documentation should be put into the
> actual source files - end user documentation should usually be lengthy.

I hope not. The API documentation is mainly a reference. So it should be 
concise rather than verbose. For functions/methods it's usually one 
sentence as brief description, optionally a short paragraph as long 
description, one phrase/short sentence per parameter and a sentence per 
relevant return value. According to my experience with the storage kit 
classes, method comments rarely exceed 15-20 lines, most are significantly 
shorter.

The BeBook features quite a bit of introducing text for most classes, 
including use cases and examples. If we do the same -- and I'd consider 
this a good idea -- those parts of the documentation are good candidates 
for separate files, but the more concise parts can as well live in the 
source files, IMHO.

> 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.

It is stable at the moment, but at some point in the future we will surely 
change it.

CU, Ingo

Other related posts: