> 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. > > >