API docs; functional or pretty?

[Thomas Zander]

On Friday 23 June 2006 14:56, Matt Rogers wrote:
First thanks for taking a longer look and providing much more usable 
feedback :)

> > - does the current dko way of having no short-text for methods,
> > forcing you to click on the method itself (and wait) help you, or
> > slow you down in finding the method name you want to use?
>
> for me, the short text clutters up the function listing, and IMHO it
> should not be generated in the function listing since not all functions
> have short-text docs.

Keeping in the back of my head that dko has a setting that if you don't 
use \brief there indeed is none; that indeed leads to the problem you 
state.
For that reason I agree with you; they should all be there, or not at all.
The solution you can see on koffice.org (which probably is not that 
visible due to the docs in the sources being ehm, shall I say, less then 
complete :)
The solution I used in gendoc.pl is to use the first sentence if there is 
no \brief in the sources.  So, if there is docs for the method, there 
will be a line visible.  Making even you happy about the overview ;)

I basically went to the route of not being anal about the correct usage of 
the doxygen style tags, using those works just as well as using the more 
commonly known javadoc style tags. Result is better docs and less 
frustrated programmers :)

-- 
Thomas Zander
-------------- next part --------------
A non-text attachment was scrubbed...
Name: not available
Type: application/pgp-signature
Size: 189 bytes
Desc: not available
URL: <http://mail.kde.org/pipermail/kde-core-devel/attachments/20060623/d4408d6d/attachment.sig>