Comments In Introspection XML?

[Simon McVittie]

On Thu, 19 Oct 2017 at 16:41:05 +1300, Lawrence D'Oliveiro wrote:
> I can think of two options for doing [documentation]:
>   * use XML comments
>   * or, add a new <annotation> type.

Neither of these is great, unfortunately. The "payload" of an <annotation>
is an attribute, not text content (PCDATA in XML jargon); so they're
fine for short annotations like the ones currently documented in the
D-Bus Specification, but they can't have newlines, significant whitespace
or markup, all of which turn out to be really useful when documenting
things.

I think the most frequent solutions for comments and documentation have
been to parse comments like GIO's gdbus-codegen does, or to introduce new
elements in a different XML namespace (Telepathy's <tp:docstring> and
org.freedesktop.Accounts' <doc>) and define them to contain HTML and/or
Docbook.

See also: https://bugs.freedesktop.org/show_bug.cgi?id=88997

The major lesson I'd draw from Telepathy, and from writing the D-Bus
Specification, is that introspection XML is not a particularly humane
format[1] to write, and neither is Docbook. When discussing D-Bus API
design I usually end up writing ad-hoc, indentation-based pseudocode
(looking vaguely like YAML containing Markdown documentation) for the
design discussion, then translating it into introspection XML (or the
data structures that a particular implementation will use to generate
introspection XML) when it's ready.

I've sometimes wondered whether a YAML-based format would make more sense
as the authoring language for D-Bus APIs, with some tool to translate
it into the introspection XML.

Regards,
    smcv

[1] in the same sense used in
    https://blog.codinghorror.com/is-html-a-humane-markup-language/