Update outdated D-Bus API docs

doc/dbus/Makefile

@@ -2,52 +2,15 @@ distdir=../dist/dbus
 tmpdir=./tmp
 
 # build HTML for GitHub pages
-all: ${distdir} ${tmpdir}
-	for f in org.opensuse.Agama*.doc.xml; do \
-	  echo $$f; \
-	  gdbus-codegen \
-	    --interface-prefix=org.opensuse.Agama. \
-	    --output-directory=${tmpdir} \
-	    --generate-docbook=ref \
-	    $$f; \
-	  docbook=${tmpdir}/ref-$${f%.doc.xml}.xml; \
-	  xmlto -o ${distdir} --skip-validation html-nochunks $$docbook; \
-	done
-	./make-index > index.html
-	cp index.html ${distdir}
+all:
+	./build-docs "${distdir}" "${tmpdir}"
 
-# 'foo 2> >(grep ... >&2)' greps stderr and keeps it as stderr
-NO_COMMENTS=xmlstarlet canonic --without-comments 2> >(grep -v 'Attempt to load network entity' >&2)
-# bash because of the >() process substitution
-SHELL=/bin/bash
+clean:
+	rm -rf "${distdir}" "${tmpdir}"
 
 # check that the implementation and documentation haven't diverged
-# TODO: factor out a script to decouple Make syntax from the rest
 diff: check
-check: ${tmpdir}
-	ALL_GOOD=true; \
-	for doc_xml in org.opensuse.Agama*.doc.xml; do \
-	  IFACE=$${doc_xml%.doc.xml}; \
-	  bus_xml=bus/$$IFACE.bus.xml; \
-	  doc_iface=${tmpdir}/$$IFACE.doc.iface.xml; \
-	  bus_iface=${tmpdir}/$$IFACE.bus.iface.xml; \
-	  \
-	  echo "Diffing $$IFACE"; \
-	  \
-	  $(NO_COMMENTS) \
-	    $${doc_xml} \
-	    > $${doc_iface}; \
-	  xmlstarlet ed \
-	    -d "//interface[@name!='$$IFACE']" \
-	    $${bus_xml} \
-	    | $(NO_COMMENTS) - \
-	    > $${bus_iface}; \
-	  diff --ignore-blank-lines --ignore-trailing-space -u $${doc_iface} $${bus_iface} || ALL_GOOD=false; \
-	done; \
-	$$ALL_GOOD
-	@echo "NO DIFF, YAY"
+check:
+	./compare-impl-and-docs "${tmpdir}"
 
-${distdir}:
-	mkdir -p $@
-${tmpdir}:
-	mkdir -p $@
+.PHONY: all diff check

doc/dbus/build-docs

@@ -0,0 +1,36 @@
+#!/bin/sh
+# Build HTML for GitHub pages
+set -eu
+
+# Workflow:
+# gdbus-codegen (glib2-devel.rpm)
+# - reads *.doc.xml introspection with comments
+# - writes ref-*.xml, DocBook refentry pieces
+# xmlto
+# - reads  ref-*.xml
+# - writes *.html
+
+# TODO opt in for a repo-wide shellcheck
+
+# TODO help message
+distdir=$1
+tmpdir=$2
+mkdir -p "$distdir" "$tmpdir"
+
+for f in org.opensuse.Agama*.doc.xml; do
+  echo "$f"
+  gdbus-codegen \
+    --interface-prefix=org.opensuse.Agama. \
+    --output-directory="$tmpdir" \
+    --generate-docbook=ref \
+    "$f"
+  docbook="$tmpdir/ref-${f%.doc.xml}.xml"
+  xmlto \
+    -o "$distdir" \
+	--skip-validation \
+	--stringparam html.stylesheet=refentry-agama.css \
+	html-nochunks \
+	"$docbook"
+done
+./make-index > "$distdir"/index.html
+cp refentry-agama.css "$distdir"

doc/dbus/bus/README.md

@@ -4,6 +4,8 @@ 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.
+  testing_using_container.sh,
+    (cd doc/dbus/bus; ./seed.sh)
 
 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
@@ -19,4 +21,4 @@ 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?
+`AGAMA_MAINFRAME_COSPLAY` flag?

doc/dbus/bus/org.opensuse.Agama.Manager1.bus.xml

@@ -35,7 +35,6 @@
       <arg name="result" direction="out" type="b"/>
     </method>
     <method name="CollectLogs">
-      <arg name="user" direction="in" type="s"/>
       <arg name="tarball_filesystem_path" direction="out" type="s"/>
     </method>
     <method name="Finish">
@@ -47,10 +46,16 @@
     <property type="b" name="IguanaBackend" access="read"/>
     <property type="as" name="BusyServices" access="read"/>
   </interface>
+  <interface name="org.opensuse.Agama1.LocaleMixin">
+    <method name="SetLocale">
+      <arg name="locale" direction="in" type="s"/>
+    </method>
+  </interface>
   <interface name="org.opensuse.Agama1.Progress">
     <property type="u" name="TotalSteps" access="read"/>
     <property type="(us)" name="CurrentStep" access="read"/>
     <property type="b" name="Finished" access="read"/>
+    <property type="as" name="Steps" access="read"/>
   </interface>
   <interface name="org.opensuse.Agama1.ServiceStatus">
     <property type="aa{sv}" name="All" access="read"/>

doc/dbus/bus/org.opensuse.Agama.Software1.bus.xml

@@ -29,6 +29,9 @@
     </signal>
   </interface>
   <interface name="org.opensuse.Agama.Software1">
+    <method name="ListRepositories">
+      <arg name="Result" direction="out" type="a(issssbb)"/>
+    </method>
     <method name="ListPatterns">
       <arg name="Filtered" direction="in" type="b"/>
       <arg name="Result" direction="out" type="a{s(sssss)}"/>
@@ -42,7 +45,8 @@
       <arg name="result" direction="out" type="b"/>
     </method>
     <method name="SetUserPatterns">
-      <arg name="ids" direction="in" type="as"/>
+      <arg name="add" direction="in" type="as"/>
+      <arg name="remove" direction="in" type="as"/>
       <arg name="wrong" direction="out" type="as"/>
     </method>
     <method name="ProvisionsSelected">
@@ -68,15 +72,23 @@
     </method>
     <method name="Finish">
     </method>
+    <signal name="ProbeFinished">
+    </signal>
     <property type="a{sy}" name="SelectedPatterns" access="read"/>
   </interface>
   <interface name="org.opensuse.Agama1.Issues">
-    <property type="a(ssuu)" name="All" access="read"/>
+    <property type="a(sssuu)" name="All" access="read"/>
+  </interface>
+  <interface name="org.opensuse.Agama1.LocaleMixin">
+    <method name="SetLocale">
+      <arg name="locale" direction="in" type="s"/>
+    </method>
   </interface>
   <interface name="org.opensuse.Agama1.Progress">
     <property type="u" name="TotalSteps" access="read"/>
     <property type="(us)" name="CurrentStep" access="read"/>
     <property type="b" name="Finished" access="read"/>
+    <property type="as" name="Steps" access="read"/>
   </interface>
   <interface name="org.opensuse.Agama1.ServiceStatus">
     <property type="aa{sv}" name="All" access="read"/>

doc/dbus/bus/org.opensuse.Agama.Storage1.bus.xml

@@ -1,12 +1,24 @@
-<!DOCTYPE node PUBLIC "-//freedesktop//DTD D-BUS Object Introspection 1.0//EN"
-"http://www.freedesktop.org/standards/dbus/1.0/introspect.dtd">
+<?xml version="1.0" encoding="UTF-8"?>
 <node name="/org/opensuse/Agama/Storage1">
-  <node name="ISCSI" />
-  <node name="iscsi_nodes" />
-  <node name="staging" />
-  <node name="system" />
-  <node name="zfcp_controllers" />
-  <node name="zfcp_disks" />
+  <node name="ISCSI"/>
+  <interface name="org.freedesktop.DBus.Introspectable">
+    <method name="Introspect">
+      <arg name="xml_data" direction="out" type="s"/>
+    </method>
+  </interface>
+  <interface name="org.freedesktop.DBus.ObjectManager">
+    <method name="GetManagedObjects">
+      <arg name="res" direction="out" type="a{oa{sa{sv}}}"/>
+    </method>
+    <signal name="InterfacesAdded">
+      <arg name="object" type="o"/>
+      <arg name="interfaces_and_properties" type="a{sa{sv}}"/>
+    </signal>
+    <signal name="InterfacesRemoved">
+      <arg name="object" type="o"/>
+      <arg name="interfaces" type="as"/>
+    </signal>
+  </interface>
   <interface name="org.freedesktop.DBus.Properties">
     <method name="Get">
       <arg name="interface_name" direction="in" type="s"/>
@@ -28,42 +40,6 @@
       <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.freedesktop.DBus.ObjectManager">
-    <method name="GetManagedObjects">
-      <arg name="res" direction="out" type="a{oa{sa{sv}}}"/>
-    </method>
-    <signal name="InterfacesAdded">
-      <arg name="object" type="o"/>
-      <arg name="interfaces_and_properties" type="a{sa{sv}}"/>
-    </signal>
-    <signal name="InterfacesRemoved">
-      <arg name="object" type="o"/>
-      <arg name="interfaces" type="as"/>
-    </signal>
-  </interface>
-  <interface name="org.opensuse.Agama1.Issues">
-    <property type="a(sssuu)" name="All" access="read"/>
-  </interface>
-  <interface name="org.opensuse.Agama1.LocaleMixin">
-    <method name="SetLocale">
-      <arg name="locale" direction="in" type="s"/>
-    </method>
-  </interface>
-  <interface name="org.opensuse.Agama1.Progress">
-    <property type="u" name="TotalSteps" access="read"/>
-    <property type="(us)" name="CurrentStep" access="read"/>
-    <property type="b" name="Finished" access="read"/>
-    <property type="as" name="Steps" access="read"/>
-  </interface>
-  <interface name="org.opensuse.Agama1.ServiceStatus">
-    <property type="aa{sv}" name="All" access="read"/>
-    <property type="u" name="Current" access="read"/>
-  </interface>
   <interface name="org.opensuse.Agama.Storage1">
     <method name="Probe">
     </method>
@@ -105,9 +81,6 @@
       <arg name="serialized_config" direction="out" type="s"/>
     </method>
   </interface>
-  <interface name="org.opensuse.Agama.Storage1.Devices">
-    <property type="aa{sv}" name="Actions" access="read"/>
-  </interface>
   <interface name="org.opensuse.Agama.Storage1.DASD.Manager">
     <method name="Probe">
     </method>
@@ -130,6 +103,9 @@
       <arg name="job" direction="out" type="o"/>
     </method>
   </interface>
+  <interface name="org.opensuse.Agama.Storage1.Devices">
+    <property type="aa{sv}" name="Actions" access="read"/>
+  </interface>
   <interface name="org.opensuse.Agama.Storage1.ISCSI.Initiator">
     <method name="Discover">
       <arg name="address" direction="in" type="s"/>
@@ -144,7 +120,7 @@
     <property type="s" name="InitiatorName" access="readwrite"/>
     <property type="b" name="IBFT" access="read"/>
   </interface>
-    <interface name="org.opensuse.Agama.Storage1.Proposal.Calculator">
+  <interface name="org.opensuse.Agama.Storage1.Proposal.Calculator">
     <method name="DefaultVolume">
       <arg name="mount_path" direction="in" type="s"/>
       <arg name="volume" direction="out" type="a{sv}"/>
@@ -157,18 +133,24 @@
     <property type="as" name="ProductMountPoints" access="read"/>
     <property type="as" name="EncryptionMethods" access="read"/>
   </interface>
-    <interface name="org.opensuse.Agama.Storage1.ZFCP.Manager">
+  <interface name="org.opensuse.Agama.Storage1.ZFCP.Manager">
     <method name="Probe">
     </method>
     <property type="b" name="AllowLUNScan" access="read"/>
   </interface>
   <interface name="org.opensuse.Agama1.Issues">
-    <property type="a(ssuu)" name="All" access="read"/>
+    <property type="a(sssuu)" name="All" access="read"/>
+  </interface>
+  <interface name="org.opensuse.Agama1.LocaleMixin">
+    <method name="SetLocale">
+      <arg name="locale" direction="in" type="s"/>
+    </method>
   </interface>
   <interface name="org.opensuse.Agama1.Progress">
     <property type="u" name="TotalSteps" access="read"/>
     <property type="(us)" name="CurrentStep" access="read"/>
     <property type="b" name="Finished" access="read"/>
+    <property type="as" name="Steps" access="read"/>
   </interface>
   <interface name="org.opensuse.Agama1.ServiceStatus">
     <property type="aa{sv}" name="All" access="read"/>

doc/dbus/bus/org.opensuse.Agama.Users1.bus.xml

@@ -1,6 +1,10 @@
-<!DOCTYPE node PUBLIC "-//freedesktop//DTD D-BUS Object Introspection 1.0//EN"
-"http://www.freedesktop.org/standards/dbus/1.0/introspect.dtd">
+<?xml version="1.0" encoding="UTF-8"?>
 <node name="/org/opensuse/Agama/Users1">
+  <interface name="org.freedesktop.DBus.Introspectable">
+    <method name="Introspect">
+      <arg name="xml_data" direction="out" type="s"/>
+    </method>
+  </interface>
   <interface name="org.freedesktop.DBus.Properties">
     <method name="Get">
       <arg name="interface_name" direction="in" type="s"/>
@@ -22,18 +26,6 @@
       <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.Agama1.Issues">
-    <property type="a(sssuu)" name="All" access="read"/>
-  </interface>
-  <interface name="org.opensuse.Agama1.ServiceStatus">
-    <property type="aa{sv}" name="All" access="read"/>
-    <property type="u" name="Current" access="read"/>
-  </interface>
   <interface name="org.opensuse.Agama.Users1">
     <method name="SetRootPassword">
       <arg name="Value" direction="in" type="s"/>
@@ -64,4 +56,11 @@
     <property type="(sbs)" name="RootUser" access="read"/>
     <property type="(sssba{sv})" name="FirstUser" access="read"/>
   </interface>
+  <interface name="org.opensuse.Agama1.Issues">
+    <property type="a(sssuu)" name="All" access="read"/>
+  </interface>
+  <interface name="org.opensuse.Agama1.ServiceStatus">
+    <property type="aa{sv}" name="All" access="read"/>
+    <property type="u" name="Current" access="read"/>
+  </interface>
 </node>