Comments In Introspection XML?
ldo at geek-central.gen.nz
Thu Oct 19 18:02:37 UTC 2017
On Thu, 19 Oct 2017 12:09:19 +0100, Simon McVittie wrote:
> 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) ...
No reason why that has to be, e.g.:
This signal is sent every time the clock chimes.
The argument is the number of clock strikes.
> ... 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.
Yes, I could adopt something like that. Apart from the HTML or DocBook.
> 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 ...
That’s OK, I was planning to generate it automatically from Python
docstrings on the server end, and conversely incorporate it
automatically into docstrings for the proxy interface at the client end.
I just want the payload in the introspection format to be plain text.
More information about the dbus