Re: [glob2-devel] changes for CVS

[Bradley Arsenault]

On 1/12/06, Stéphane Magnenat <address@hidden> wrote:
> Hi,
>
> > - put http://globulation2.org/wiki/Changes in the changelog file
>
> Well, we should do a nice script that does this automatically :-)
>
> > - remove file DONE
>
> DONE ;-) (i.e. DONE is removed)
>
> > - at line 56 in metaserver/metaserver.cpp
> > /**
> > * @bool YOGServer::init()
> > * takes no input
> > * returns true if the YOGServer properly started
> > * returns false if it did not
> > **/
> >
> > 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
>
> --
> http://nct.ysagoon.com
>
>
> _______________________________________________
> glob2-devel mailing list
> address@hidden
> http://lists.nongnu.org/mailman/listinfo/glob2-devel
>

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.