documentation and introspection

Simon McVittie simon.mcvittie at
Mon Nov 20 04:07:13 PST 2006

I've done some work on converting the Telepathy specification to an
ad-hoc XML format based on D-Bus introspection (it was previously
defined by Python docstrings!). It seems what I've tried to do for the
Telepathy spec is somewhat more ambitious than your doc:description
extension - hopefully some or all of it can be included in doc:, at
which point we'll convert the Telepathy spec to that format.

On Fri, 17 Nov 2006 at 15:54:07 +0000, Matthew Johnson wrote:
> I'd like a single-line description for each interface/method at least
> (<doc:description>).

The Telepathy spec was previously written using Python "docstring"
conventions (loosely, Python's equivalent of Javadoc or Doxygen - see for details). This means each
interface and each method has a multi-paragraph description. The
published Telepathy spec more or less consists only of these descriptions,
so for us it's important that there's sufficient text there.

This is why I didn't use the existing annotation mechanism - the text of
an annotation is an XML attribute, and attributes don't preserve
whitespace or allow markup.



	Top level element for the spec "wrapper" XML


	The version of the specification


	Currently, the text content is the interface name with the
	org.freedesktop.Telepathy. prefix missing; for an interface
	Channel.Type.Text the XSLT reads ChannelTypeText.xml. Obviously,
	that'd have to be generalized a bit if using a similar format
	for non-Telepathy uses.

<tp:include-errors href="...">

	Load the given XML file which describes errors



	One or more Copyright (C) ... lines (but no other text)


	The standard "This library is free software" LGPL blurb


	The Python-style docstring (on an interface, method, signal
	or at the top level of the specification)

Flags and enums

<tp:flags name="ChannelGroupFlags">
	<tp:flag name="CHANNEL_GROUP_FLAG_CAN_ADD" value="1"/>
	<tp:flag name="CHANNEL_GROUP_FLAG_CAN_REMOVE" value="2"/>
	<tp:flag name="CHANNEL_GROUP_FLAG_CAN_RESCIND" value="4"/>

	A set of flags which are expected to be bitwise-OR'ed together.
	Should turn out as an enum in languages where enums can take
	arbitrary values (C), or a collection of constants in
	languages where enums can only take named values (Java, Pascal)
	or don't exist (Python).

	The XSLT (or whatever) is expected to prepend a
	suitable prefix for languages without namespacing
	(the type and value become TpChannel... and TP_CHANNEL... in
	C), or leave the name as-is for languages with namespaces
	(the value becomes telepathy.constants.TP_CHANNEL_... in

<tp:enum name="ChannelGroupChangeReason">
	<tp:enumvalue name="CHANNEL_GROUP_CHANGE_REASON_NONE" value="0"/>

	An enumeration. Should turn out as an enum in languages which
	have them, or a collection of constants in languages which don't
	have enums. Again, the XSLT (or whatever) is expected to prepend a
	suitable prefix for languages without namespacing.



	Wrapper for all error declarations

<tp:error name="org.freedesktop.Telepathy.Error.MiscError" python="MiscError">

	Describes an error. Contains a <tp:docstring>. The python
	attribute gives a Python name for the error (Channel.Full ->
	ChannelFull) - if none is given the last component of the name
	is used. (This needs generalizing, obviously.)


The XML version of the Telepathy spec includes XSLT to translate:

- enums/flags to C
- errors to a GLib error enumeration
- interfaces to #defined C constants
- the whole spec to HTML
- enums/flags to Python
- errors to Python exceptions
- interfaces to Python string constants
- interfaces to dbus-python dbus.service.Interface subclasses
- the spec to official D-Bus introspection data (i.e. remove all the
  Telepathy extensions)

More information about the dbus mailing list