Re: Where to document APIs?

sön 2008-04-20 klockan 22:14 -0600 skrev Alex Rousskov:
> The current suggestions are:
>
> .dox (in docs/Programming Guide or in src/, not clear) -- 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:11:41 MDT