[PATCH-API-DOCU] AbstractRunner documentation

[Aaron J. Seigo]

On Monday 27 October 2008, Sebastian Trüg wrote:
> Hi guys,
>
> while implementing the Nepomuk Search runner I stumbled over the
> incomplete, partially outdated, and partially wrong documentation of
> Plasma::AbstractRunner. I tried to fix it as far as I could from looking at
> the code. Please review the attached patch.
> The patch also contains a few comments on the API; mainly questions. As you
> want to move libplasma to kdelibs soon, this is maybe the last opportunity
> to fix a few issues.

i haven't read through your added docu (i trust you on that =), but did take a 
look at the questions and here are some answers:

+        // trueg: why is this method not protected?

because it can be called by other classes if they don't care to do async 
matching in threads (or external processes, i suppose). at this point we could 
probably make it protected if we wanted to as nothing probably uses it.

+        // trueg: why having a reference to the context. This is very weird 
when storing it
+        //        for async operations

you can make copies of the context just fine; it's a non-const reference to 
allow for future features where runners can add their own bits of information 
to the context during processing. maybe we'll take advantage of that someday 
=P

+        // trueg: what do we need the term for? It is stored in the context 
anyway! Plus: matches() does not have a term parameter!

it's needed to match the term with the context's current term. since it's 
threaded the following can happen:

* match is called with term "kon"
* runner goes off looks up "konsole" and "konqueror"
* meanwhile the user types 's'
* the runner tries to register its two matches with term "kon"; the context 
has changed, however (the runner doesn't know that yet!), and so it knows it 
can discard it

iow, it's there to fix race conditions between the user input and runner 
returning matches =)

> Sidenote: is it intended to not support async runners directly?

well, it is what it is. we don't need async runners now that we use threads, i 
guess =)

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

-------------- next part --------------
A non-text attachment was scrubbed...
Name: not available
Type: application/pgp-signature
Size: 197 bytes
Desc: This is a digitally signed message part.
Url : http://mail.kde.org/pipermail/plasma-devel/attachments/20081027/f678722b/attachment.sig