-
Notifications
You must be signed in to change notification settings - Fork 75
Fix D-Bus docs after ZFCP and Questions changes #628
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
Merged
Merged
Changes from all commits
Commits
Show all changes
9 commits
Select commit
Hold shift + click to select a range
d5ec086
doc/dbus/bus: update .bus.xml
mvidner 7c4d43b
doc/dbus/bus: adjust seeding Questions from Rust
mvidner 2055399
doc/dbus/bus: Questions1.Generic now properly declared
mvidner 189abc5
doc/dbus/bus: Agama1.Manager +Finish +IguanaBackend
mvidner 8a55cf3
doc/dbus: Storage1
mvidner f966dfc
doc: make check: move it to backend_doc CI job that runs in all branches
mvidner 1a5f036
doc/dbus: Questions1.Generic and .LuksActivation moved from dbus_api.md
mvidner 367bade
doc/dbus: better bus/README.md
mvidner dab1e5b
doc/dbus: add title to make-index
mvidner File filter
Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
There are no files selected for viewing
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
|
|
@@ -6,4 +6,4 @@ all: | |
| cp index.html dist | ||
|
|
||
| check: | ||
| $(MAKE) -C dbus diff | ||
| $(MAKE) -C dbus check | ||
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -1 +1,22 @@ | ||
| FIXME: describe how to maintain these (semi)automatically | ||
| The `*.bus.xml` files here are produced by introspecting actual objects | ||
| exported by the Agama services. | ||
|
|
||
| The files are produced by `seed.sh`. | ||
| - FIXME: run it in CI. | ||
| - FIXME: make it easy to run it *and* commit the result to git. | ||
|
|
||
| Each file name represents a D-Bus **interface** that we want to document. | ||
| That is why some files have symlinks pointing to them (and why you see no | ||
| `org.freedesktop.DBus.*` filenames, we don't need to document those interfaces) | ||
|
|
||
| The interfaces implemented in Rust already have documentation in them | ||
| (courtesy of Rust macro magic) but it is not in the exact format that | ||
| `gdbus-codegen` understands :sob:. | ||
|
|
||
| You are expected to copy a new `foo.bus.xml` to `../foo.doc.xml`, remove the | ||
| `<interface>` elements other than `foo`, and add meaningful documentation. | ||
| Run `make check`. | ||
|
|
||
| FIXME: Storage1.ZFCP and Storage1.DASD needs an s390 machine to run, | ||
| we should expose them on x86 too (returning errors), perhaps guarded by an | ||
| `AGAMA_IGNORE_ARCH` flag? |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
50 changes: 31 additions & 19 deletions
50
doc/dbus/bus/org.opensuse.Agama.Questions1.Generic.bus.xml
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -1,37 +1,49 @@ | ||
|
|
||
| <!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/opensuse/Agama/Questions1/1"> | ||
| "http://www.freedesktop.org/standards/dbus/1.0/introspect.dtd"> | ||
| <node> | ||
| <interface name="org.freedesktop.DBus.Properties"> | ||
| <method name="Get"> | ||
| <arg name="interface_name" direction="in" type="s"/> | ||
| <arg name="property_name" direction="in" type="s"/> | ||
| <arg name="value" direction="out" type="v"/> | ||
| <arg name="interface_name" type="s" direction="in"/> | ||
| <arg name="property_name" type="s" direction="in"/> | ||
| <arg type="v" direction="out"/> | ||
| </method> | ||
| <method name="Set"> | ||
| <arg name="interface_name" direction="in" type="s"/> | ||
| <arg name="property_name" direction="in" type="s"/> | ||
| <arg name="val" direction="in" type="v"/> | ||
| <arg name="interface_name" type="s" direction="in"/> | ||
| <arg name="property_name" type="s" direction="in"/> | ||
| <arg name="value" type="v" direction="in"/> | ||
| </method> | ||
| <method name="GetAll"> | ||
| <arg name="interface_name" direction="in" type="s"/> | ||
| <arg name="value" direction="out" type="a{sv}"/> | ||
| <arg name="interface_name" type="s" direction="in"/> | ||
| <arg type="a{sv}" direction="out"/> | ||
| </method> | ||
| <!-- | ||
| Emits the `org.freedesktop.DBus.Properties.PropertiesChanged` signal. | ||
| --> | ||
| <signal name="PropertiesChanged"> | ||
| <arg name="interface" type="s"/> | ||
| <arg name="interface_name" type="s"/> | ||
| <arg name="changed_properties" type="a{sv}"/> | ||
| <arg name="invalidated_properties" type="as"/> | ||
| </signal> | ||
| </interface> | ||
| <interface name="org.freedesktop.DBus.Peer"> | ||
| <method name="Ping"> | ||
| </method> | ||
| <method name="GetMachineId"> | ||
| <arg type="s" direction="out"/> | ||
| </method> | ||
| </interface> | ||
| <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> | ||
| <interface name="org.freedesktop.DBus.Introspectable"> | ||
| <method name="Introspect"> | ||
| <arg name="xml_data" direction="out" type="s"/> | ||
| <arg type="s" direction="out"/> | ||
| </method> | ||
| </interface> | ||
| <interface name="org.opensuse.Agama.Questions1"> | ||
| <property type="u" name="Id" access="read"/> | ||
| <property type="s" name="Text" access="read"/> | ||
| <property type="as" name="Options" access="read"/> | ||
| <property type="s" name="DefaultOption" access="read"/> | ||
| <property type="s" name="Answer" access="readwrite"/> | ||
| </interface> | ||
| </node> | ||
|
|
62 changes: 37 additions & 25 deletions
62
doc/dbus/bus/org.opensuse.Agama.Questions1.LuksActivation.bus.xml
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -1,41 +1,53 @@ | ||
|
|
||
| <!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/opensuse/Agama/Questions1/2"> | ||
| "http://www.freedesktop.org/standards/dbus/1.0/introspect.dtd"> | ||
| <node> | ||
| <interface name="org.freedesktop.DBus.Introspectable"> | ||
| <method name="Introspect"> | ||
| <arg type="s" direction="out"/> | ||
| </method> | ||
| </interface> | ||
| <interface name="org.freedesktop.DBus.Peer"> | ||
| <method name="Ping"> | ||
| </method> | ||
| <method name="GetMachineId"> | ||
| <arg type="s" direction="out"/> | ||
| </method> | ||
| </interface> | ||
| <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> | ||
| <interface name="org.freedesktop.DBus.Properties"> | ||
| <method name="Get"> | ||
| <arg name="interface_name" direction="in" type="s"/> | ||
| <arg name="property_name" direction="in" type="s"/> | ||
| <arg name="value" direction="out" type="v"/> | ||
| <arg name="interface_name" type="s" direction="in"/> | ||
| <arg name="property_name" type="s" direction="in"/> | ||
| <arg type="v" direction="out"/> | ||
| </method> | ||
| <method name="Set"> | ||
| <arg name="interface_name" direction="in" type="s"/> | ||
| <arg name="property_name" direction="in" type="s"/> | ||
| <arg name="val" direction="in" type="v"/> | ||
| <arg name="interface_name" type="s" direction="in"/> | ||
| <arg name="property_name" type="s" direction="in"/> | ||
| <arg name="value" type="v" direction="in"/> | ||
| </method> | ||
| <method name="GetAll"> | ||
| <arg name="interface_name" direction="in" type="s"/> | ||
| <arg name="value" direction="out" type="a{sv}"/> | ||
| <arg name="interface_name" type="s" direction="in"/> | ||
| <arg type="a{sv}" direction="out"/> | ||
| </method> | ||
| <!-- | ||
| Emits the `org.freedesktop.DBus.Properties.PropertiesChanged` signal. | ||
| --> | ||
| <signal name="PropertiesChanged"> | ||
| <arg name="interface" type="s"/> | ||
| <arg name="interface_name" type="s"/> | ||
| <arg name="changed_properties" type="a{sv}"/> | ||
| <arg name="invalidated_properties" type="as"/> | ||
| </signal> | ||
| </interface> | ||
| <interface name="org.freedesktop.DBus.Introspectable"> | ||
| <method name="Introspect"> | ||
| <arg name="xml_data" direction="out" type="s"/> | ||
| </method> | ||
| </interface> | ||
| <interface name="org.opensuse.Agama.Questions1"> | ||
| <property type="u" name="Id" access="read"/> | ||
| <property type="s" name="Text" access="read"/> | ||
| <property type="as" name="Options" access="read"/> | ||
| <property type="s" name="DefaultOption" access="read"/> | ||
| <property type="s" name="Answer" access="readwrite"/> | ||
| </interface> | ||
| <interface name="org.opensuse.Agama.Questions1.LuksActivation"> | ||
| <property type="s" name="Password" access="readwrite"/> | ||
| <property type="u" name="Attempt" access="read"/> | ||
| <property name="Attempt" type="y" access="read"/> | ||
| <property name="Password" type="s" access="readwrite"/> | ||
| </interface> | ||
| </node> | ||
|
|
||
Oops, something went wrong.
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
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.
Uh oh!
There was an error while loading. Please reload this page.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
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:
In general, something similar to what UDisks2 does. What do you think?
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
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.mdabout this.There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
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.