KDE libs documentation policy

[Tim Jansen]

On Sunday 05 October 2003 21:46, you wrote:
> > - 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)
> What if the description is more than once sentence long?

Then I add the period.
After looking at some java.lang.* classes Java mixes both styles as well. 
Sometimes simple sentences end with a period, sometimes they dont. 

> Another thing that came to mind. Think about a width() function for a
> widget. If it doesn't anything but return the width, the description for
> this function reads something like "Returns the width of the widget".
> Should there still be a "@return the width of the widget"?

Yes, definitely. If doxygen is smart enough to derive a default description 
from "@return the width of the widget" we may get away with only writing the 
@return field (I dont think it is). But a function with return value should 
have a @return, because
a) people do not read reference documentation, they scan it for the 
information that they need. This is why it is important that everything is at 
the place they expect it to be.
b) a non-HTML documentation viewer (e.g. in a IDE) may decide to display only 
the function name, @param and @return in order to conserve screen space. You 
lose meta data if you hide information in the description.

bye...