23 Mar
2011
23 Mar
'11
8:24 p.m.
2011/3/23 Jon Cruz <jon@...18...>:
- start with "/**"
- have the first sentence as a brief description, and be sure to end with a period '.'
- comment a function/method in the .h and not the .cpp (if it is in both)
...
Documenting in the .h is contentious. My opinion is: if the function is defined only in the header (inline), put the docs in the header. But if it's defined in .cpp, put the docs above the definition in .cpp, so documentation changes won't trigger extensive recompiles.
I would add 1. If there is a @file comment at the top, do not include the author information in it - put it in a separate normal comment 2. Use /** */ and /// instead of /*! */ and //! 3. For one-line documentation of class members, use ///< after the member 4. Be careful to document what you are intending to, not e.g. the Inkscape namespace
Regards, Krzysztof