Inclusion of documentation in introspection data?

[John (J5) Palmieri]

On Mon, 2005-10-24 at 17:54 +0200, Tako Schotanus wrote:
> Robert McQueen wrote:
> 
> >John (J5) Palmieri wrote:
> >  
> >
> >>I was thinking of adding it as an annotation.  In fact python can do
> >>this without spec changes if we want to.  We eventually wanted to have
> >>it so you could do print proxy_obj.__doc__ and get documentation.  The
> >>biggest problem is bandwidth.  Good documentation can easily become
> >>bigger than the introspect data itself.  Do we want to go down that
> >>road?
> >>    
> >>
> >
> >Yeah thats what we were thinking about too. You could perhaps add a
> >layer of indirection like an annotation which says there is
> >documentation available, and a method to request them by? Would allow
> >things to be a bit lazier, but would the Python bindings end up just
> >getting all the strings, just causing a load more bus round trips?
> >
> >
> >  
> >
> Or two different ways of asking for introspection data: terse vs full.
> Of course this either means another method in the Introspection 
> interface or an argument to the existing method.
> 
> For hand-crafted introspection data you could just say that 
> documentation should be as short as possible but that doesn't work of 
> course for generated bindings.
> 
> But it sounds good, anything that favors "discovery" where you can just 
> look around on the bus to see what services are available and what 
> actions they support is okay in my book :-)
> 
> Cheers,
>  -Tako
> _______________________________________________
> dbus mailing list
> dbus at lists.freedesktop.org
> http://lists.freedesktop.org/mailman/listinfo/dbus

This doesn't seem to be a 1.0 issue since it can be done by adding
annotations and methods.  It does seem valuable so if someone wants to
implement them in the python bindings as a
org.freedesktop.DBus.Python.Doc annotation that is fine.  If you want to
make it more generic just don't use org.freedesktop.DBus.Doc or anything
that might become part of the final spec after 1.0.  This is because we
want to figure out what works first and if we have to break things it is
better to figure it out on a namespace that is not going to be the
official namespace.  In the end it will be easy to move over.

-- 
John (J5) Palmieri <johnp at redhat.com>