tim at tjansen.de
Sat Sep 7 19:51:06 BST 2002
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...
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).
More information about the kde-core-devel