Where is the documentation

[Matthew Johnson]

On Fri Sep 19 14:39, Mihail Kotelnikov wrote:
> I tried to write dbus-powered application about three years ago. I've not 
> found any documentation except short function/data types reference.
> Some days ago i've returned to this problem. And what i see? After three years 
> of development project's documentation stays on the same level. In particular, 
> there is no documentation conforming to the status of the project (linux 
> message bus standard i mean). Function reference IS NOT a documentation. There 
> is no complete examples (sorry, but sleep(1) IS NOT example of a working main 
> loop), best practice explanation and so on. You suggest to use higher level 
> bindings, but it's documentation is worse than documentation of the raw API.
> Yes, i can to bury myself in the dbus code, function reference and pieces of 
> third-party half-working examples and write a [half-]working code. But it 
> isn't the best way to write stable and efficient application for a production use.
> 

There's not much low level documentation because, as you point out,
people are not meant to write apps using it, they are meant to use a
binding. I can't comment on the documentation status for all of the
bindings, but some of them at least do have good documentation. For
example, Java[0,1], Python[2,3], Perl[4] and QT[5]. You were presumably
looking at dbus-glib before which also has documentation[6] as well as
examples. I don't know if this has improved since you were looking.

Yes, there is certainly room for improvement. In general DBus projects
are short on man power. I'm the only dbus-java developer, for example,
aside from a few people submitting patches occasionally. In
single-person projects there's often a push to improve the code first
rather than the documentation, but to say there's _none_ is a little
exaggeration. And there's no mainloop example code in the low-level
bindings since it's not about writing a main loop, it's assumed if you
are coding against the lowlevel API you will already know how to do
that.

I do agree that it would be good to have better 'best practices'
documentation. It's not entirely clear, however, what those best
practices are.

Matt

0. http://dbus.freedesktop.org/doc/dbus-java/dbus-java/
1. http://dbus.freedesktop.org/doc/dbus-java/api/
2. http://dbus.freedesktop.org/doc/dbus-python/doc/tutorial.html
3. http://dbus.freedesktop.org/doc/dbus-python/api/index.html
4. http://search.cpan.org/~danberr/Net-DBus-0.33.1/lib/Net/DBus/Tutorial.pod
5. http://doc.trolltech.com/4.2/intro-to-dbus.html
6. http://dbus.freedesktop.org/doc/dbus-glib/
-- 
www.matthew.ath.cx
D-Bus Java
-------------- 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/20080919/fdc769ed/attachment.pgp