dbus-glib - removing the generated bus method wrappers

[Daniel P. Berrange]

On Wed, Jul 26, 2006 at 10:30:34AM -0400, Havoc Pennington wrote:
> Matthew Johnson wrote:
> >The use case is someone reading the API (which I think should be
> >generated from the XML then rendered in some fashion, or just reading
> >the XML equivelently) to implement a server or a client and not having
> >to founder around because there are no docs (which I've done several
> >times with dbus apps). Having a way to provide a short description
> >easily with your introspection data will help enormously in getting
> >people to actually write these.
> 
> Even if we say OK, the docs are in the introspection data xml (which 
> does still raise the issue of how it gets there if not hand-writing said 
> xml), the problem I brought up remains though - what format are the docs 
> in? Are we inventing our own format? Is it "plain text"? How does one 
> correctly display these docs?

One thing is certain - unless it is in a format that we can automatically
generate from the programming language's native docs, its never going to 
be filled out. With the Perl bindings I've tried to make it possible to
write DBus objects in a manner which is as close to normal Perl OO style
as possible. The only place where DBus creaps in is when you annotate
methods to provide their data type signatures. In such a scenario the
developer nevers gets exposed to the existance of Introspection XML or 
similar. Likewise for documentationm, they will already be writing POD
documentation for all APIs, so the liklihood of them also writing a DBus
specific set of docs is essentially zero.

So I'd say inventing our own format is a non-starter, and we must stick
with something very simple. For Perl's POD format there are convertors to
plain text, html, man or latex[1]. The granularity of docs only really goes 
down to per-method level - certainly no commonly used syntax for annotating
individual parameters.  So if we do define a way to annotate parameters
bear in mind that it must be optional / not relied upon.

Regards,
Dan,

[1] There is a way to write additional convertor backends, but its a 
    non-trivial amount of work, so please don't mention DocBook ;-)
-- 
|=-            GPG key: http://www.berrange.com/~dan/gpgkey.txt       -=|
|=-       Perl modules: http://search.cpan.org/~danberr/              -=|
|=-           Projects: http://freshmeat.net/~danielpb/               -=|
|=-   berrange at redhat.com  -  Daniel Berrange  -  dan at berrange.com    -=|
-------------- next part --------------
A non-text attachment was scrubbed...
Name: not available
Type: application/pgp-signature
Size: 189 bytes
Desc: Digital signature
Url : http://lists.freedesktop.org/archives/dbus/attachments/20060726/174e1e7a/attachment.pgp