Re: Where to document APIs?

> sön 2008-04-20 klockan 22:14 -0600 skrev Alex Rousskov:
>> The current suggestions are:
>>
<snip>

.h (as a second-best as .dox in src/) -- Amos

>> .dox (in src/) -- Kinkie.
>> .h (or perhaps .cc) -- Henrik.
>
> To clarify:
>
> Longer API documents, .dox file in docs/, or maybe src/ next to the .cc
>
> Basic rules the code need to fulfill, or until the API documentation
> grows large, in the .h or .cc file.
>
>> 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.
>
> I disagree here, I find it a lot easier to make sure the basic
> documentation is there if in the same file as the implementation. But
> the Squid project is not a good example in either direction as we do not
> have any history of actually keeping any kind of documentation up to
> date, neither inline or in separate documents.. (only the opposite)
>
>> There are plenty of outdated comments in Squid sources, for example.
>
> True.. just as there is plenty of outdated code...
>
> But I usually kill them (both) these days if touching nearby code..
>
> Regards
> Henrik
>
>
Received on Tue Apr 22 2008 - 13:20:49 MDT