State of Plasma API documentation

[Aaron J. Seigo]

On May 18, 2010, Sebastian Trüg wrote:
> I recently found myself in the situation where I wanted to implement a
> simple popup menu in a Plasma applet. I had to use C++ since the menu is
> dynamic and an existing C++ class. The problem was that I had no idea
> what to do other than using something like QToolButton which looks ugly
> and does not even work properly (menu pops up in the wrong place).
> 
> I had a look in the Plasma API docs which contains gazillion of classes,
> many of which have close to no documentation.

which classes did you look at that have "close to no documentation"? we've 
tried quite hard to keep the documentation pretty complete on the public API. 
if you can give more details as t what holes you found, we can perhaps fille 
them.
 
> I ended up trying IconWidget which seemed the right choice (the #plasma
> irc channel did not get my any further)

you could always try the mailing list. which you evidently know about.

> but that class does not work
> very nice either. It does not scale with the panel 

it doesn't scale only if you are doing something wrong. can you point us to 
this code you are writing, explain the desired end goals, describe the exact 
problems you are having, etc?
 
> and seems pretty unmaintained alltogether.

we try not to touch things that aren't broken. don't confuse that for not 
maintained. though i'd be interested in what gave you that impression in the 
first place.

> On top of that the docu contains a lot of private classes. IMHO that is

yes, those should be removed from the docs.

> Thus, I would ask that someone takes the time to at least add the proper
> Doxygen hints to the Mainpage.dox to exclude the private classes. And

i'm working on it now; i don't usually generate the docs locally and i have 
near zero experience chnging the doxygen configuration, so hopefully i succeed 
without too much time spent on it. also, please feel free to make such 
improvements yourself as well so you aren't left waiting on us.

> maybe the maintainers of the Plasma classes could add a brief
> description to each class so one can understand their purpose.

i'll put it on my todo. though honestly, adding "IconWidget is a widget 
providing an icon, optionally with an action." is a pretty low value return on 
my time. if you can't figure out that IconWidget is a widget that shows an 
icon, i'm not sure any amount of documentation is going to help you out.

i'd rather invest time tutorials and examples, as those seem to have greater 
"flattening the learning curve" impacts.

-- 
Aaron J. Seigo
humru othro a kohnu se
GPG Fingerprint: 8B8B 2209 0C6F 7C47 B1EA  EE75 D6B7 2EB1 A7F1 DB43

KDE core developer sponsored by Qt Development Frameworks
-------------- next part --------------
A non-text attachment was scrubbed...
Name: not available
Type: application/pgp-signature
Size: 198 bytes
Desc: This is a digitally signed message part.
Url : http://mail.kde.org/pipermail/plasma-devel/attachments/20100518/bf67cac9/attachment.sig