Re: Where to document APIs?

On Mon, 2008-04-21 at 00:55 +0200, Henrik Nordstrom wrote:
> sön 2008-04-20 klockan 12:23 -0600 skrev Alex Rousskov:
>
> > At this point, I am interested in collecting formal API guarantees, not
> > writing a true Guide, but it feels like .dox files should go into
> > doc/Programming-Guide.
>
> Shouldn't thise go into the .h or .cc next to the code?

That was one of the original options I proposed (wiki, .cc, .h). Amos
suggested .dox files instead.

API docs may be too big to go into .h or .cc. Personally, when I read
code, I want to focus on the code and not have to skip over pretty
formatted comments that ramble about that code. One or two succinct
lines per class name, function, or member is all I need (those lines can
refer to detailed documentation elsewhere, of course). Perhaps that is
just me though; I am happy to follow whatever API documentation method
we pick!

The current suggestions are:

.dox (in docs/Programming Guide or in src/, not clear) -- Amos.
.dox (in src/) -- Kinkie.
.h (or perhaps .cc) -- Henrik.

What do others prefer?

Thanks,

Alex.
P.S. BTW, I do not give much weight to "keep them close so that they are
updated" arguments because in my experience documentation freshness
depends on code review and the size of the comment, not its location.
There are plenty of outdated comments in Squid sources, for example.
Received on Tue Apr 22 2008 - 14:17:13 MDT