[packagekit] API Documentation

[Richard Hughes]

On Mon, 2008-02-11 at 12:34 +0000, Thomas Wood wrote:
> I have a few queries about the API documentation:
> 
> * The Search methods do not seem explain what the method is supposed to
> do. For example, it is not clear what search group should do. Should it
> search the available groups or search within a group? If searching
> within a group, what field should it search on?

It should return all packages in a group, i.e. "search for * in group x"

> * I presume the 101 progress value is now deprecated, and the "no
> progress updates" function should be used instead?

Well, there's a choice. If you need to report unknown progress you can
now use the percentage_changed function or the no_percentage_updates
function. I might remove the latter if you think that's a good idea.

> * There is no stipulation on how many times the progress callback can be
> used and what the valid values are. pkcon appears to have difficulties
> if 100% is sent multiple times.

Ohh, news to me. I'll try this tonight - maybe we can add this as a self
test? How does it fail?

> * Sub-percentage is not explained, and there doesn't appear to be any
> way for the backend to communicate how many sub-transactions there are
> and which sub-transaction is currently being reported (maybe use status
> method?).

Subpercentage is the amount the sub-transaction has progressed. The
number of sub transactions is not exported to the user, although this is
probably a useful thing to know for the GUI. I know apt and yum can
report this so it may be useful to add a new method. We can't coalesce
these methods into a super method (like Progress) as some backends won't
have the concept of a transaction, let alone sub-transaction steps.

> Could anyone give me some pointers on these? Are there any plans to use
> gtk-doc for the backend methods and signals?

A good idea, although every time I try to play with gtk-doc then I spend
a couple of hours crying with automake to fix make distcheck. I think
gtk-doc should already scan src/ and libpackagekit/ - maybe I've done
something wrong. If we could - if would be good to move the static html
documentation into gtk-doc comments, as a static file tends to get out
of date pretty quickly. 

Richard.