API docs; functional or pretty?

[Matt Rogers]

On Friday 23 June 2006 08:20, Thomas Zander wrote:
> 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 ;)
>

That's cool. Now, if the docs were complete, we wouldn't need that, but we'll 
save that for another thread (or two or three) :)

> 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 :)

Can we possibly expect to see some of your improvements on dev.k.o soon? In 
this case,  I'm specifically talking about the contrast difference between 
the function documentation and the page background.

Thanks
--
Matt