Fix D-Bus docs after ZFCP and Questions changes#628
Conversation
Pull Request Test Coverage Report for Build 5322725513
💛 - Coveralls |
| <arg type="s" direction="out"/> | ||
| </method> | ||
| </interface> | ||
| <interface name="org.opensuse.Agama.Questions1.Generic"> |
There was a problem hiding this comment.
Questions1.Generic is defined three times (Questions1.bus.xml, Questions1.Generic.bus.xml and Questions1.LuksActivation.bus.xml). Is that expected? I am not sure if that is the best way for documenting objects with dynamic interfaces.
There was a problem hiding this comment.
In fact, I think the file names could be misleading. For example, I would expect that doc/dbus/bus/org.opensuse.Agama.Questions1.Generic.bus.xml defines the Questions1.Generic interface, but it defines all the interfaces of an object that only includes Questions1.Generic interface.
I would expect to have both, object docs and interface docs. And an object doc only includes the name of the interfaces, for example:
doc/dbus/objects/question/generic.xml
<node name="/org/opensuse/Agama/Storage1/questions/[0-9]+">
<interface name="org.freedesktop.DBus.Introspectable" />
<interface name="org.freedesktop.DBus.Peer" />
<interface name="org.opensuse.Agama.Questions1.Generic" />
</node
doc/dbus/objects/question/luks_activation.xml
<node name="/org/opensuse/Agama/Storage1/questions/[0-9]+>
<interface name="org.freedesktop.DBus.Introspectable" />
<interface name="org.freedesktop.DBus.Peer" />
<interface name="org.opensuse.Agama.Questions1.Generic" />
<interface name="org.opensuse.Agama.Questions1.LuksActivation" />
</node
doc/dbus/interfaces/org.opensuse.Agama.Questions1.Generic.xml
<interface name="org.opensuse.Agama.Questions1.Generic">
<property name="Answer" type="s" access="readwrite"/>
<property name="DefaultOption" type="s" access="read"/>
<property name="Id" type="u" access="read"/>
<property name="Options" type="as" access="read"/>
<property name="Text" type="s" access="read"/>
</interface>
In general, something similar to what UDisks2 does. What do you think?
There was a problem hiding this comment.
Questions1.Generic is defined three times (Questions1.bus.xml, Questions1.Generic.bus.xml and Questions1.LuksActivation.bus.xml).
Well no, it is documented once in .doc.xml, and mentioned in the introspection output of a generic question, and of a Luks question which must include it because it is a subclass. I'll improve bus/README.md about this.
ooAQ1.Generic.doc.xml
bus/ooAQ1.Generic.bus.xml
bus/ooAQ1.LuksActivation.bus.xml
There was a problem hiding this comment.
I would expect to have both, object docs and interface docs.
Very good point, I have so far concentrated on the automated part and limited the output to the interfaces.
We also need documenting the objects (object trees) and which interfaces they implement. Probably some manually written pieces.
joseivanlopez
left a comment
joseivanlopez
left a comment
There was a problem hiding this comment.
LGTM, but opening a discussion about the doc organization.
uninteresting changes: - Locale1 now includes Peer and Properties
include the unimportant introspection changes
had to manually restore s390 interfaces that were omitted on x86_64
[skip CI]
3 participants
Problem
After merging the ZFCP changes (#594) to master, CI fails because it thinks the D-Bus API and its docs have diverged. Well it has, but...
Solution
The diff is messy because Ruby and Rust have random differences in equivalent introspection XML :-/
Reviewing by commits helps that a bit.
Testing