Standardise documentation format in introspection XML
Submitted by Philip Withnall
Assigned to D-Bus Maintainers
Description
There are several documentation formats available for use with introspection XML, none of which are recommended over the others as they all have disadvantages. This is a bit of a fractured and confusing situation for newcomers to D-Bus.
If we could standardise on a single format (either one of the existing ones, or a new one with none of their disadvantages), that would be excellent.
Current formats I know of, together with their positives and negatives: • XML comments containing gtk-doc syntax (preferred by gdbus-codegen)
- Allows arbitrary newlines in documentation.
- Requires a special parser to interpret.
- Not structurally tied to the interface description (e.g. you can remove an argument from a method, but its documentation would still be present in the comment). • GDBus annotations (org.gtk.GDBus.DocString) (supported by gdbus-codegen but not preferred)
- Structurally tied to the interface description.
- Machine readable, although doesn’t expose much metadata.
- Doesn’t allow arbitrary newlines; stored as an XML attribute. • ‘doc’ namespace, http://www.freedesktop.org/dbus/1.0/doc.dtd (I have no idea what uses this; org.freedesktop.Accounts does, amongst others)
- Machine readable, exposing a reasonable amount of metadata.
- Allows arbitrary newlines.
- Unsupported by tools?
From this, it looks like the ‘doc’ namespace is in the lead, but I can’t find any information about it anywhere. Or a DTD.
Version: git master