documentation and introspection

[Simon McVittie]

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
http://www.python.org/dev/peps/pep-0257/ 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.

Structure
=========

<tp:spec>

	Top level element for the spec "wrapper" XML

<tp:version>

	The version of the specification

<tp:interface>

	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

Text
====

<tp:copyright>

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

<tp:license>

	The standard "This library is free software" LGPL blurb

<tp:docstring>

	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
	Python).

<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.

Errors
======

<tp:errors>

	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.)

====
XSLT
====

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)