Comments In Introspection XML?
smcv at collabora.com
Thu Oct 19 11:09:19 UTC 2017
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
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
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 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.
 in the same sense used in
More information about the dbus