Comments In Introspection XML?

[Lawrence D'Oliveiro]

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

    <annotation name="comment">
        This signal is sent every time the clock chimes.
        The argument is the number of clock strikes.
    </annotation>

> ... 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[1] 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.