yade-users team mailing list archive

[Bruno Chareyre <bruno.chareyre@xxxxxxxxxxx>]

> After the voting, people will offfer who does what (presumably
> scratching his itch). I don't think there will be many volunteers for
> writing documentation ;-p
>   
Actually, the doxygen documentation should be the documentation base.
I know Vaclav is writing precise and complete comments in doxygen style 
in his classes, I started to do the same in some classes, and if you 
browse dox-doc a bit you realize that it works well.
One big advantage of this is that there is not ONE guy to write the 
documentation, but many.
Even the average user trying to understand a class can comment a 
variable with "/// comment on x...", when he finally found the meaning 
of x. Then, after commit, it will update the documentation immediatly.

The conclusions are :
-Encourage all users to comment the code if they can.
-Encourage them to commit to svn (yes if more users commit stuff, there 
is a bigger chance of breaking things, but considering that currently 
most users are so afraid of commiting something wrong that they commit 
nothing, I think self-control is strong enough and we can encourage them 
to commit a bit more - and anyway subversion is designed in such a way 
that it's impossible to really break Yade).

For all users :

-The simplest "doxygen style" comment in a .hpp file is with 3 slash bars :

class something
{

/// Description of x
int x;

}

and it will result in x being listed, with the comment, in the doxygen 
documentation about class "something".


For a more general description of a class, it is almost the same idea : 
type the comment just before the declaration of the class, but for a 
multiline comment, use " /*! " instead of " /// ", as in clump.hpp below.


/*! Body representing clump (rigid aggregate) composed by other existing 
bodies.

    Clump is one of bodies that reside in rootBody->bodies.
    When an existing body is added to ::Clump, it's ::Body::isDynamic 
flag........
    .....
 
 */

class Clump: public Body {

....

}


Bruno



-- 
 
_______________
Chareyre Bruno
Maitre de conference

Institut National Polytechnique de Grenoble
Laboratoire 3S (Soils Solids Structures) - bureau E145
BP 53 - 38041, Grenoble cedex 9 - France
Tél : 33 4 56 52 86 21
Fax : 33 4 76 82 70 43
________________

_______________________________________________
Yade-users mailing list
Yade-users@xxxxxxxxxxxxxxxx
https://lists.berlios.de/mailman/listinfo/yade-users