KDoc Styleguide

[Tim Jansen]

Hi...

Is there a style guide for kdocs? I am trying to add missing documentation in 
the kdelibs headers, and I think it is a problem that there is no common 
style for the entries. As I am currently writing many docs, I would prefer to 
have a common style soon, in order to avoid reverting too much later...

Questions:
There are several ways to comment a parameter, for example:
 * @param userName the new name of the user
 * @param userName is the new name of the user.
 * @param userName This specifies the new name of the user
 * @param userName This argument specifies the new name of the user.
Which one is preferable?

Should you escape constants?
   * @return @p true if the URL has a reference part
   * @return true if the URL has a reference part

Are there any other things to take care of?


And something else. PLEASE document what your method does when an error 
occurred, something is not initialized or something unusual happened. 
Especially methods that return QStrings or pointers often return 
QString::null or 0L, but in most kdocs this is not mentioned at all. Most of 
the time, that I need for documenting kdelibs, is spent reading the code and 
finding out which values can be returned by a method. 
If a method can return QString::null or a null pointer, always document this. 
Otherwise the reader will assume that this can not happen (unless he is wise 
enough to check every single return value because you cant trust kdelibs).

bye...