Re: Comments In Introspection XML?
Lawrence D'Oliveiro <ldo-kC51rjc0cqs1dNLGKZg6taU/[email protected]>
| Newsgroups | gmane.comp.freedesktop.dbus |
|---|---|
| Organization | Geek Central |
| Message-ID | <[email protected]> |
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.
_______________________________________________
dbus mailing list
[email protected]
https://lists.freedesktop.org/mailman/listinfo/dbus