Re: Doxygen comments in code

[Benjamin Kosnik <bkoz at redhat dot com>]

> To that end, I'm soliciting opinions on what we should document for each
> public class, variable, and function.  Just an overview?  Each parameter?
> Something in between those two?  Keep in mind that we can release an
> encyclopedia if we want for 3.1.  Also keep in mind that the more we want
> documented, the more help I'll need (my wrists get sore enough from typing
> already :-).

I'd be happy if class data members and public member functions were 
documented, as well as types. That seems sufficient for the time being. I'd 
like to start simple, and then work up to something more complicated. I'd 
also like to avoid undue complication and needless complexity if at all 
possible...

It seems to be a sensible thing to try to get the formatting right on a 
relatively simple class before marking up everything. I suggest std::string.
This means basic_string.h, std_string.h, basic_string.tcc, and 
char_traits.h would have to be documented.

Does this sound like a good starting place to you? 

> Initially I'd like to drop placeholder text in everywhere we plan on
> documenting for 3.0; that way people can easily see whether a particular
> thing has been documented yet or not.  Contributors then don't have to
> ask where/what/whether a thing should be documented.

Not quite sure I understand you. It seems to me that another approach 
would be to just document bits correctly, and the undocumented bits are 
not done. Once the style sheet and formatting are ok'd, they we can ask 
for volunteers to do specific files or groups of files. Even four people 
could probably do the whole library in a week, I think.

I'm planning on volunteering to help you: it's going to take a lot of 
work and I'd hate for one person to have to do it all.

-benjamin