AUG
1
2006

More Kraziness

We have a new "pass-by-value" check in Krazy written by Andreas. It is the first plugin written in C++ (and not perl). And it requires Qt4. So, we had to do a bit of tweaking of things on the EBN. Seems to be working well.

Check out your favorite code's kraziness.

On the APIDOX front: I'm thinking about re-writing the doxygen.sh script in kdelibs/doc/api. Possibly in perl.
I think this one script is trying to be too many things to too many people. And I'd really like our APIDOX to look more like the Qt4 doc (QString). I like how Qt puts the argument description in-line with the method description, and doesn't clutter things up with separate @param and @return stuff.

Comments

Wouldn't it make sense for Krazy to produce patches for a lot of the problems? So long as it ran a short while ago so that there aren't any conflicts, you could then (for example) download and apply a patch against the 106 instances of QStrings being used instead of QChars in Kopete (report).


By Tom Chance at Tue, 08/01/2006 - 18:04

If Krazy ever becomes that smart then we could simply fix the code automagically without human intervention at all.

But a "download patch to fix these issues" might be a good thing to consider. In the future. We are still learning what developers like and don't like about the EBN. My overriding rule with Krazy is to not irritate the developers. Being one myself and all...


By awinterz at Tue, 08/01/2006 - 19:50

    I like how Qt puts the argument description in-line with the method description

What do you mean with that? The thing I dislike most about Qts docs is the absence of descriptions.

Oh; and you may want to look at trunk/koffice/doc/api/gendocs.pl :)


By Thomas Zander at Tue, 08/01/2006 - 18:11

I like:

"Sets the widget color to @p color".

better than:

"Set the widget color.
@param color the color to set the widget to"


By awinterz at Tue, 08/01/2006 - 19:44

ok.

I can't actually find that in the linked page (after fixing the url). Can you give a example of where that is used? The dislike I noted before is exactly because I can't find them. So I'm really surprised that you find their presence usefull. I must be missing something.

Also; I hope that you are not suggesting the removal of the table of arguments? As a reference guide (which API docs are more often than not) its annoying to have to read the whole story just to figure out what a parameter is used for.


By Thomas Zander at Tue, 08/01/2006 - 19:59

[QString dox link fixed]

Just like any writing we can talk about style all day long. For short 'set' and 'get' methods the @param and @return always seem redundant and usually silly to me. And these kind of methods make up a large chunk of the apidox.

I agree that for more complicated methods the argument tables are a necessity. The apidox should be readable/understandable/translatable?/navigable and... complete. I'll be happy just to improve on what we have now.


By awinterz at Tue, 08/01/2006 - 21:08