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.