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.

I mentioned it as an unlisted alternative.
I still prefer the .h as primary .

>
> 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 - 13:20:48 MDT