Re: [glob2-devel] changes for CVS

[Nuage]

Bradley Arsenault wrote:
>>>or how should we do documentation on the different functions?
>>
>>We should document functions in the cpp file using doxygen syntax. This has
>>the advantage not to make the header unreadable and let people more freedom
>>to write more things. Inline functions should also be documented in the cpp
>>file using the ability of doxygen to document a function anywhere by
>>specifying which function the doc refers to.
>>
>>If we want to document members variable in the h file, that is ok, but the
>>comment should be placed after the member in the same line, such as:
>>int numberOfPlayers; //!< the number of player in the game, must be bigger
>>than 0 and lower than 32
>>
>>Steph
> 
> 
> Its best (or atleast I think) to document the usage of the
> function/method, (rather than the implementation), in the header file
> so that it is easily accessible. Documentation on the implementation
> of a function or method should not be done with doxygen, because that
> information is really only important when your actually changing the
> source, in which case you would generally have the function in front
> of you.

Sorry, but I disagree. People tend to make allot of redundant documentation.
This makes the headers files much longer to read. If the comments are put into
the header, tree lines of comments for one method makes me four times slower to
find the method I want. Or more generally to read the header. Oppositely,
comments in the implementation file is needed right at the time you want to 
read it.

We should not mix the people learning the code and the ones maintaining it. So
please, don't slow me down...thank you.

Nuage