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
