Re: Where to document APIs?

On Fri, 2008-09-12 at 22:28 +0200, Henrik Nordstrom wrote:
> On tor, 2008-09-11 at 09:54 -0600, Alex Rousskov wrote:
>
> > You mean as a large blob of comments at the end of some .h file? The
> > cons are:
>
> I think Adrian is thinking more of blobs next to the implementations
> (.cc)
>
>
> As time has passed a little I have this slightly refined view:
>
> * Overview type documentation for a class, not tied to a specific
> method/member:
>
> - small, in the .h file
>
> - larger, in the .cc or a src/class.dox, whatever suits the author
> best. Personal preference is the .cc as it's that way more likely to be
> remembered to update documentation when updating the implementation.
>
> - when there is no single .cc file matching the class. A src/class.dox
> file, or rework of the implementation to get a cleaned match between .h
> and .cc files...

> * High level overviews or other not tied to a specific class or
> implementation
>
> .dox files

So where would you put Comm and AsyncCall API notes I have posted? I am
guessing .dox because they are not tied to a specific class, right?

Thanks,

Alex.
Received on Fri Sep 12 2008 - 22:55:09 MDT