[RFC] Standard documentation strings

[Simon McVittie]

On 30/08/12 00:25, Sanel Zukan wrote:
> However, this feature differs between implementations and bindings:
> GDBus would use org.gtk.GDBus.DocString annotation and EggDBus (is it
> still used?) has similar approach.

The problem with annotations is that they can only contain things valid
in an XML attribute, which doesn't include structured XML markup. So you
can have docstrings written in gtk-doc syntax, but you can't have
docstrings written in XHTML. I'm also not sure whether whitespace inside
attributes (in particular, newlines) is treated as significant.

> However, I noticed some Qt
> introspection xml files would use <tp:docstring> tag

The <tp:*> elements originate from Telepathy. We intended our augmented
introspection format (described on
<http://telepathy.freedesktop.org/wiki/DbusSpec>) to be something that
would be consumed by our own tools, rather than generic D-Bus tools -
they're not compatible with the D-Bus DTD (which doesn't allow arbitrary
elements, and probably can't, due to the limitations of DTDs), so we
remove them during processing, and don't make them available over D-Bus.

<tp:docstring> contains XHTML 1.0, so we can have nicely structured
documentation that produces HTML, which is nice for complex interfaces
(like Telepathy).

I think I've also seen people use Docbook. We didn't use that in
Telepathy because it's even more verbose than XHTML.

Ideally, if I wasn't constrained by compatibility, I'd like to write
most of the Telepathy specification in some more wiki-like format,
perhaps Markdown. The problem with that is that ad-hoc text languages
(Markdown, reStructured Text, Creole, gtk-doc, etc.) are not
particularly suitable for standardization and interoperability: they
tend to have a rather vague language definition, resulting in either a
single implementation in someone's pet programming language whose source
code is the de facto definition of the language, or multiple
implementations in various languages with their own incompatible extensions.

Python docstrings try to evade the "what format is this?" problem by not
having any standard format at all: there are markers you can use to
indicate that they're rST, but the lowest common denominator is just
ASCII text. I'm not convinced this is the way forward for something
intended to improve interoperability.

Perhaps the solution is to standardize on something like HTML or Docbook
for interoperability on D-Bus, and have tools that convert an
easier-to-write language (e.g. Markdown) into the chosen format during
compilation?

    S