xmlgen should generate docs based on the doc comments in input XML

[zeenix]

trafficstars

In GitLab by @tim-seoss on Nov 2, 2020, 15:57

DBus Interface definitions usually include documenting comments, e.g. the following excerpt :

<?xml version="1.0" encoding="UTF-8" ?>

<!--
 ModemManager 1.0 Interface Specification

   Copyright (C) 2008 Novell, Inc.
   Copyright (C) 2008-2013 Red Hat, Inc.
   Copyright (C) 2011-2013 Google, Inc.
   Copyright (C) 2011-2013 Lanedo GmbH
-->

<node name="/" xmlns:doc="http://www.freedesktop.org/dbus/1.0/doc.dtd">

  <!--
      org.freedesktop.ModemManager1:
      @short_description: The ModemManager Manager interface.

      The Manager interface allows controlling and querying the status of the
      ModemManager daemon.
  -->
  <interface name="org.freedesktop.ModemManager1">

    <!--
        ScanDevices:

        Start a new scan for connected modem devices.
    -->
    <method name="ScanDevices" />

    <!--
        SetLogging:
        @level: One of <literal>"ERR"</literal>, <literal>"WARN"</literal>, <literal>"INFO"</literal>, <literal>"DEBUG"</literal>.

        Set logging verbosity.
    -->
    <method name="SetLogging">
      <arg name="level" type="s" direction="in" />
    </method>

zbus-xmlgen currently discards these, and creates its own entries such as:

/// ScanDevices method
fn scan_devices(&self) -> zbus::Result<()>;

It would be useful if the comments could be carried over. serde-xml-rs doesn't appear (at initial quick inspection) to offer a mechanism to read XML comments, so it may be necessary to use the underlying xml-rs to access (just) the comment data?

n.b. Although the interface definitions from package source code / documentation etc. include these comments, XML returned by org.freedesktop.DBus.Introspectable.Introspect doesn't.

[zeenix]

It would be useful if the comments could be carried over.

A simple "carry over" won't be enough. The doc comments needs to be parsed and converted. gdbus-codegen already does that so we can look at it's source to see how/what it does for inspiration.

As for the other comments (non-doc), I don't think we need to do anything about those.

XML returned by org.freedesktop.DBus.Introspectable.Introspect doesn't.

Correct and the reason is AFAIK that the xml is typically generated (our own implementation doesn't included the docs either) at runtime. However, I don't think we need to worry about this fact.

[zeenix]

As for the other comments (non-doc), I don't think we need to do anything about those.

Actually, I wouldn't mind those being carried over verbatim but not strong feelings.