Is it possible and good to add a facility for including documentation in the introspection output?

[mulkieran]

Looking in files in /usr/share/dbus-1/interfaces on my machine I notice that a number of them, e.g., org.fedoraproject.Config.Printing.xml include a bunch of xml which consists of doc specifications. Here is a snippet from the beginning of the file:

<!DOCTYPE node PUBLIC
 "-//freedesktop//DTD D-BUS Object Introspection 1.0//EN"
 "http://www.freedesktop.org/standards/dbus/1.0/introspect.dtd">

<node name="/org/fedoraproject/Config/Printing"
      xmlns:doc="http://www.freedesktop.org/dbus/1.0/doc.dtd">
  <interface name="org.fedoraproject.Config.Printing">
    <doc:doc>
      <doc:description>
        <doc:para>
          This interface is for configuring printing.
        </doc:para>
      </doc:description>
    </doc:doc>
        
    <method name="NewPrinterDialog">
      <doc:doc>
        <doc:description>
          <doc:para>
            Create a New Printer dialog object.
          </doc:para>
        </doc:description>
      </doc:doc>

I do not know where the idea arose that it was ok to put these additional tags in the introspection data. I know that these doc tags are not explicit in the very old DTD which was once used to specify the introspection data format.

Below is a list of all the files that use the <doc:doc> tag on my machine:

/usr/share/dbus-1/interfaces/org.freedesktop.Accounts.User.xml:
/usr/share/dbus-1/interfaces/org.fedoraproject.Config.Printing.xml:
/usr/share/dbus-1/interfaces/org.freedesktop.PackageKit.xml:
/usr/share/dbus-1/interfaces/org.freedesktop.Tracker3.Miner.Files.Index.xml:
/usr/share/dbus-1/interfaces/org.freedesktop.bolt.xml:
/usr/share/dbus-1/interfaces/org.freedesktop.ColorManager.xml:
/usr/share/dbus-1/interfaces/org.freedesktop.ColorManager.Device.xml:
/usr/share/dbus-1/interfaces/org.freedesktop.ColorManager.Sensor.xml:
/usr/share/dbus-1/interfaces/org.freedesktop.ColorManager.Profile.xml:
/usr/share/dbus-1/interfaces/org.freedesktop.ColorHelper.xml:
/usr/share/dbus-1/interfaces/org.freedesktop.Accounts.xml:
/usr/share/dbus-1/interfaces/org.freedesktop.PackageKit.Transaction.xml:

Note that they are mostly official freedesktop interfaces, so presumably this approach is not totally frowned upon.

I cloned PackageKit at https://github.com/PackageKit/PackageKit.git, and noticed that the introspection data is provided as a file in the source tree. I didn't dig deeply into the build system or try to find out how it is used.

But having seen that, I have the question in the title: Is it possible and good to add a facility for including documentation in the introspection output?

Why is this on my mind? Well, without it, we end up editing the introspection data by hand to add better documentation for our users. We currently do it like this: https://stratis-storage.github.io/manager.xml . It is pretty tedious to do it for every new release. It would be nice if we could generate the docs programmatically, instead.

The annotation facility, which was briefly considered, does not seem appropriate.

What would have to be added would be a new method on interfaces, methods, and args, which allowed adding documentation for these elements.

[diwic]

It is both possible and good, but I don't have the time myself to implement it right now. I'm happy to review a PR.

Looking at https://dbus.freedesktop.org/doc/dbus-api-design.html#documentation there are at least three different ways of commenting:

• XML comments <!-- -->, listed as "preferred" in the api design document
• Annotation with name="org.gtk.GDBus.DocString"
• <doc:doc> - but that's in an example somewhere else in the document outside of the "documentation" section

I'm okay with supporting any or all of these but if you're exploring, can you do a quick check if any of the other two are more common than the doc:doc stuff you're suggesting?

Also annotations are probably the simplest to implement as there is already some support for it (deprecations) in dbus-codegen. What is the reason that is not appropriate here?

[mulkieran]

Thanks for the link!

There were a few considerations regarding annotations:

1. dbus-rs seems to only allow annotating at the interface and method level (not at the arg level). I might have made too much of that.
2. I have never seen annotations used for anything so free form as documentation. I'm accustomed only to ones with well-defined and commonly accepted meanings and associated conventions, like org.freedesktop.DBus.Property.EmitsChangedSignal . I guess now I have seen annotations used for documentation.

We currently hand-enter gtk-doc-style comments into the introspection output. The reason why I was doubtful about that being correct in the long term is that they are generic comments on the XML, and I wasn't certain they would be the best to read programmatically to describe what the methods, args, and interfaces are for. Of course, the link you gave me states that that format is preferred, and a search makes it seem pretty usual.

Regarding the <doc:doc> approach, that seemed the best structured, with the caveat that it isn't specified in the way old DTD.

I'll ask further.

[mulkieran]

@mvollmer Could you give an opinion on how best to programmatically insert comments in the introspection data?