KDE libs documentation policy

[Tim Jansen]

On Sunday 05 October 2003 05:46, Benjamin Meyer wrote:
> A few ideas:
> -All public and protected functions much have documentation.
> -If class is a widget have a screenshot.
> -If applicable a demo usage in the class description.
> -An example application which shows usage of the class.

A few more basic things are also needed:
- the capitalization of @param and @return fields (I prefer lower case at the 
beginning and no '.' at the end. Java style is lower-case with '.', KDE mixes 
both)
- the order of the fields, as this matters in doxygen (I always use 
description, @param, @return, @exception, @see, @since)
- a preferred style for short summaries or the first sentence of the 
description (e.g. "KMyClass is a class to do cool things", or "A class to do 
cool things." or "Does cool things"...). Without this the class overview gets 
confusing. 
- Depending on the last point, a decision whether @short should be used or we 
make our live easier (but possibly the short description more complicated) by 
always writing a summary as first sentence of the description, so doxygen can 
pick it up
- should @author be used, and who is the author? the author of the docs? the 
original author of the function? the maintainer?
- functions returning boolean as success state. Should 'false' be mentioned 
("true if blablabla succeeded, false otherwise" vs. "true if blablabla 
succeeded")

bye...