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.
This would be nice, but I don't see it happening particularly soon.
(In reply to Simon McVittie from comment #1) > This would be nice, but I don't see it happening particularly soon. I think all it should take is a bit of discussion (or executive decision) and updating the official guidelines in the documentation (I’m happy to do that). I don’t think we need to port existing modules to use the new standard; but at least get something established so that new modules don’t continue to be fractured. The ‘doc’ namespace seems to be the best contender to me.
The other alternative is to punt on specifying an officially recommended documentation format for the XML introspection format, and instead simply defining one for the structured replacement for XML: bug #98006. In that bug, I’m suggesting allowing a{sv} annotations in all places in the introspection data, and specifying documentation as an org.freedesktop.DBus.Introspection2.Documentation annotation with type a{ss}. The a{ss} value should map a locale name (see `man setlocale`, e.g. ‘en_GB’) to a documentation string in that locale. I suspect most documentation will end up being in ‘en_US’. The documentation should be written in Markdown format. Since introspection data is not returned as XML, whitespace is significant, so we no longer have the problem of losing newlines.
(In reply to Philip Withnall from comment #0) > • ‘doc’ namespace, http://www.freedesktop.org/dbus/1.0/doc.dtd I get the following error accessing this document: Not Found - The requested URL /dbus/1.0/doc.dtd was not found on this serverers)
(In reply to Ralf Habacker from comment #4) > (In reply to Philip Withnall from comment #0) > > > • ‘doc’ namespace, http://www.freedesktop.org/dbus/1.0/doc.dtd > I get the following error accessing this document: Not Found - The requested > URL /dbus/1.0/doc.dtd was not found on this serverers) Yup, as far as I know that DTD has never been defined formally.
(In reply to Philip Withnall from comment #5) > (In reply to Ralf Habacker from comment #4) > > (In reply to Philip Withnall from comment #0) > > > > > • ‘doc’ namespace, http://www.freedesktop.org/dbus/1.0/doc.dtd > > I get the following error accessing this document: Not Found - The requested > > URL /dbus/1.0/doc.dtd was not found on this serverers) > > Yup, as far as I know that DTD has never been defined formally. With bug 89011 they are now installed and public. Time to make it also public on the server ?
(In reply to Ralf Habacker from comment #6) > With bug 89011 they are now installed and public. Time to make it also > public on the server ? No, Bug #89011 is about the introspection DTD. As far as I know, http://www.freedesktop.org/dbus/1.0/doc.dtd has never existed or been maintained by the D-Bus maintainers; it's a just case of a third party project prematurely assuming that their proposed addition to D-Bus will be accepted (which in fact it wasn't).
-- GitLab Migration Automatic Message -- This bug has been migrated to freedesktop.org's GitLab instance and has been closed from further activity. You can subscribe and participate further through the new bug through this link to our GitLab instance: https://gitlab.freedesktop.org/dbus/dbus/issues/120.
Use of freedesktop.org services, including Bugzilla, is subject to our Code of Conduct. How we collect and use information is described in our Privacy Policy.