KDE libs documentation policy

[Benjamin Meyer]

-----BEGIN PGP SIGNED MESSAGE-----
Hash: SHA1

On Sunday 05 October 2003 8:59 am, Tim Jansen wrote:
> 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)

You mean @param vs @Param? and '.' at the end of the sentance?  It should be 
noted that Qt doesn't use @param, @return at all, but simply has sentances 
that make reference to all of the args and return value.  Does kde want to 
behave similar to Qt?

> - the order of the fields, as this matters in doxygen (I always use
> description, @param, @return, @exception, @see, @since)

If this looks then best then so be it :)  Could probably write some script to 
fix this and the above.

> - 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?

You can have multiple authors.  author refers to the code writer(s).  is there 
a @maintainer field?

> - functions returning boolean as success state. Should 'false' be mentioned
> ("true if blablabla succeeded, false otherwise" vs. "true if blablabla
> succeeded")
You should only have to mention one of the two states.  "true if going to 
mars."

- -Benjamin Meyer

- -- 
Public Key: http://www.csh.rit.edu/~benjamin/public_key.asc
-----BEGIN PGP SIGNATURE-----
Version: GnuPG v1.0.6 (GNU/Linux)
Comment: For info see http://www.gnupg.org

iD8DBQE/gEOH1rZ3LTw38vIRAh6UAJ95IXvsstExU+N9xmexD57Y776SegCcC/We
No4u/o0bvciwM53mLSvDoAU=
=weqN
-----END PGP SIGNATURE-----