Merge pull request systemd#29150 from abderrahim/version-info-dbus

man: add version information for dbus interfaces
iaguis · Sep 19, 2023 · 02ee98d · 02ee98d
2 parents c71404f + d0c0c10
commit 02ee98d
Show file tree

Hide file tree

Showing 8 changed files with 251 additions and 3 deletions.
diff --git a/man/org.freedesktop.hostname1.xml b/man/org.freedesktop.hostname1.xml
@@ -418,4 +418,16 @@ node /org/freedesktop/hostname1 {
     <para>David Zeuthen's original Fedora
     <ulink url="https://fedoraproject.org/wiki/Features/BetterHostname">Feature page about xdg-hostname</ulink></para>
   </refsect1>
+
+  <refsect1>
+    <title>History</title>
+    <refsect2>
+      <title>The D-Bus API</title>
+      <para><varname>FirmwareVersion</varname> and
+      <function>GetHardwareSerial()</function> were added in version 251.</para>
+      <para><varname>OperatingSystemSupportEnd</varname>,
+      <varname>FirmwareVendor</varname>, and
+      <varname>FirmwareDate</varname> were added in version 253.</para>
+    </refsect2>
+  </refsect1>
 </refentry>
diff --git a/man/org.freedesktop.login1.xml b/man/org.freedesktop.login1.xml
@@ -1505,4 +1505,23 @@ node /org/freedesktop/login1/session/1 {
   </refsect1>
 
   <xi:include href="org.freedesktop.locale1.xml" xpointer="versioning"/>
+
+  <refsect1>
+    <title>History</title>
+    <refsect2>
+      <title>The Manager Object</title>
+      <para><varname>HandlePowerKeyLongPress</varname>,
+      <varname>HandleRebootKey</varname>,
+      <varname>HandleRebootKeyLongPress</varname>,
+      <varname>HandleSuspendKeyLongPress</varname>, and
+      <varname>HandleHibernateKeyLongPress</varname> were added in version 251.</para>
+      <para><varname>StopIdleSessionUSec</varname> was added in version 252.</para>
+      <para><function>PrepareForShutdownWithMetadata</function> was added in version 255.</para>
+    </refsect2>
+    <refsect2>
+      <title>Session Objects</title>
+      <para><function>SetDisplay()</function> was added in version 252.</para>
+      <para><function>SetTTY()</function> was added in version 254.</para>
+    </refsect2>
+  </refsect1>
 </refentry>
diff --git a/man/org.freedesktop.machine1.xml b/man/org.freedesktop.machine1.xml
@@ -670,4 +670,18 @@ $ gdbus introspect --system \
   </refsect1>
 
   <xi:include href="org.freedesktop.locale1.xml" xpointer="versioning"/>
+
+  <refsect1>
+    <title>History</title>
+    <refsect2>
+      <title>The Manager Object</title>
+      <para><function>CopyFromMachineWithFlags()</function> and
+      <function>CopyToMachineWithFlags()</function> were added in version 252.</para>
+    </refsect2>
+    <refsect2>
+      <title>Machine Objects</title>
+      <para><function>CopyFromWithFlags()</function> and
+      <function>CopyToWithFlags()</function> were added in version 252.</para>
+    </refsect2>
+  </refsect1>
 </refentry>
diff --git a/man/org.freedesktop.network1.xml b/man/org.freedesktop.network1.xml
@@ -573,4 +573,16 @@ $ gdbus introspect --system \
   </refsect1>
 
   <xi:include href="org.freedesktop.locale1.xml" xpointer="versioning"/>
+
+  <refsect1>
+    <title>History</title>
+    <refsect2>
+      <title>DHCPv4 Client Object</title>
+      <para><varname>State</varname> was added in version 255.</para>
+    </refsect2>
+    <refsect2>
+      <title>DHCPv6 Client Object</title>
+      <para><varname>State</varname> was added in version 255.</para>
+    </refsect2>
+  </refsect1>
 </refentry>
diff --git a/man/org.freedesktop.oom1.xml b/man/org.freedesktop.oom1.xml
@@ -95,4 +95,12 @@ node /org/freedesktop/oom1 {
   </refsect1>
 
   <xi:include href="org.freedesktop.locale1.xml" xpointer="versioning"/>
+
+  <refsect1>
+    <title>History</title>
+    <refsect2>
+      <title>The Manager Object</title>
+      <para><function>Killed</function> was added in version 252.</para>
+    </refsect2>
+  </refsect1>
 </refentry>
diff --git a/man/org.freedesktop.portable1.xml b/man/org.freedesktop.portable1.xml
@@ -566,4 +566,17 @@ node /org/freedesktop/portable1 {
   </refsect1>
 
   <xi:include href="org.freedesktop.locale1.xml" xpointer="versioning"/>
+
+  <refsect1>
+    <title>History</title>
+    <refsect2>
+      <title>The Manager Object</title>
+      <para><function>GetImageStateWithExtensions()</function> was added in version 251.</para>
+    </refsect2>
+    <refsect2>
+      <title>The Image Object</title>
+      <para><function>GetStateWithExtensions()</function> was added in version 251.</para>
+      <para><function>ReattachWithExtensions()</function> was added in version 254.</para>
+    </refsect2>
+  </refsect1>
 </refentry>
diff --git a/man/org.freedesktop.systemd1.xml b/man/org.freedesktop.systemd1.xml
@@ -11502,4 +11502,168 @@ $ gdbus introspect --system --dest org.freedesktop.systemd1 \
   </refsect1>
 
   <xi:include href="org.freedesktop.locale1.xml" xpointer="versioning"/>
+
+  <refsect1>
+    <title>History</title>
+    <refsect2>
+      <title>The Manager Object</title>
+      <para><varname>RuntimeWatchdogPreUSec</varname> and
+      <varname>RuntimeWatchdogPreGovernor</varname> were added in version 251.</para>
+      <para><varname>WatchdogDevice</varname>,
+      <varname>WatchdogLastPingTimestamp</varname>,
+      <varname>WatchdogLastPingTimestampMonotonic</varname>,
+      <varname>DefaultDeviceTimeoutUSec</varname>,
+      <function>DumpUnitsMatchingPatterns()</function>, and
+      <function>DumpUnitsMatchingPatternsByFileDescriptor()</function> were added in version 252.</para>
+      <para><function>GetUnitByPIDFD()</function> and
+      <function>DisableUnitFilesWithFlagsAndInstallInfo()</function> were added in version 253.</para>
+      <para><varname>ConfidentialVirtualization</varname>,
+      <varname>DefaultIOAccounting</varname>,
+      <varname>DefaultIPAccounting</varname>,
+      <varname>DefaultMemoryPressureThresholdUSec</varname>,
+      <varname>DefaultMemoryPressureWatch</varname>,
+      <function>QueueSignalUnit()</function>,
+      <function>SoftReboot()</function>, and
+      <function>DumpUnitFileDescriptorStore()</function> were added in version 254.</para>
+    </refsect2>
+    <refsect2>
+      <title>Unit Objects</title>
+      <para><varname>Upholds</varname> and
+      <varname>UpheldBy</varname> were added in version 251.</para>
+      <para><varname>AccessSELinuxContext</varname> and
+      <varname>ActivationDetails</varname> were added in version 252.</para>
+      <para><function>QueueSignal()</function> was added in version 254.</para>
+    </refsect2>
+    <refsect2>
+      <title>Service Unit Objects</title>
+      <para><varname>ControlGroupId</varname> and
+      <varname>ExtensionDirectories</varname> were added in version 251.</para>
+      <para><varname>OpenFile</varname>,
+      <varname>ReloadSignal</varname>,
+      <varname>MemoryZSwapMax</varname>, and
+      <varname>LogFilterPatterns</varname> were added in version 253.</para>
+      <para><varname>RestartMode</varname>,
+      <varname>RestartSteps</varname>,
+      <varname>RestartMaxDelayUSec</varname>,
+      <varname>RestartUSecNext</varname>,
+      <varname>FileDescriptorStorePreserve</varname>,
+      <function>DumpFileDescriptorStore()</function>,
+      <varname>DelegateSubgroup</varname>,
+      <varname>DefaultStartupMemoryLow</varname>,
+      <varname>StartupMemoryLow</varname>,
+      <varname>StartupMemoryHigh</varname>,
+      <varname>StartupMemoryMax</varname>,
+      <varname>StartupMemorySwapMax</varname>,
+      <varname>StartupMemoryZSwapMax</varname>,
+      <varname>MemoryPressureWatch</varname>,
+      <varname>MemoryPressureThresholdUSec</varname>,
+      <varname>RootEphemeral</varname>,
+      <varname>ImportCredential</varname>,
+      <varname>MemoryKSM</varname>,
+      <varname>RootImagePolicy</varname>,
+      <varname>MountImagePolicy</varname>, and
+      <varname>ExtensionImagePolicy</varname> were added in version 254.</para>
+    </refsect2>
+    <refsect2>
+      <title>Socket Unit Objects</title>
+      <para><varname>ControlGroupId</varname> and
+      <varname>ExtensionDirectories</varname> were added in version 251.</para>
+      <para><varname>MemoryZSwapMax</varname> and
+      <varname>LogFilterPatterns</varname> were added in version 253.</para>
+      <para><varname>DelegateSubgroup</varname>,
+      <varname>DefaultStartupMemoryLow</varname>,
+      <varname>StartupMemoryLow</varname>,
+      <varname>StartupMemoryHigh</varname>,
+      <varname>StartupMemoryMax</varname>,
+      <varname>StartupMemorySwapMax</varname>,
+      <varname>StartupMemoryZSwapMax</varname>,
+      <varname>MemoryPressureWatch</varname>,
+      <varname>MemoryPressureThresholdUSec</varname>,
+      <varname>RootEphemeral</varname>,
+      <varname>ImportCredential</varname>,
+      <varname>MemoryKSM</varname>,
+      <varname>RootImagePolicy</varname>,
+      <varname>MountImagePolicy</varname>, and
+      <varname>ExtensionImagePolicy</varname> were added in version 254.</para>
+      <para><varname>PollLimitIntervalUSec</varname> and
+      <varname>PollLimitBurst</varname> were added in version 255.</para>
+    </refsect2>
+    <refsect2>
+      <title>Mount Unit Objects</title>
+      <para><varname>ControlGroupId</varname> and
+      <varname>ExtensionDirectories</varname> were added in version 251.</para>
+      <para><varname>MemoryZSwapMax</varname> and
+      <varname>LogFilterPatterns</varname> were added in version 253.</para>
+      <para><varname>DelegateSubgroup</varname>,
+      <varname>DefaultStartupMemoryLow</varname>,
+      <varname>StartupMemoryLow</varname>,
+      <varname>StartupMemoryHigh</varname>,
+      <varname>StartupMemoryMax</varname>,
+      <varname>StartupMemorySwapMax</varname>,
+      <varname>StartupMemoryZSwapMax</varname>,
+      <varname>MemoryPressureWatch</varname>,
+      <varname>MemoryPressureThresholdUSec</varname>,
+      <varname>RootEphemeral</varname>,
+      <varname>ImportCredential</varname>,
+      <varname>MemoryKSM</varname>,
+      <varname>RootImagePolicy</varname>,
+      <varname>MountImagePolicy</varname>, and
+      <varname>ExtensionImagePolicy</varname> were added in version 254.</para>
+    </refsect2>
+    <refsect2>
+      <title>Swap Unit Objects</title>
+      <para><varname>ControlGroupId</varname> and
+      <varname>ExtensionDirectories</varname> were added in version 251.</para>
+      <para><varname>MemoryZSwapMax</varname> and
+      <varname>LogFilterPatterns</varname> were added in version 253.</para>
+      <para><varname>DelegateSubgroup</varname>,
+      <varname>DefaultStartupMemoryLow</varname>,
+      <varname>StartupMemoryLow</varname>,
+      <varname>StartupMemoryHigh</varname>,
+      <varname>StartupMemoryMax</varname>,
+      <varname>StartupMemorySwapMax</varname>,
+      <varname>StartupMemoryZSwapMax</varname>,
+      <varname>MemoryPressureWatch</varname>,
+      <varname>MemoryPressureThresholdUSec</varname>,
+      <varname>RootEphemeral</varname>,
+      <varname>ImportCredential</varname>,
+      <varname>MemoryKSM</varname>,
+      <varname>RootImagePolicy</varname>,
+      <varname>MountImagePolicy</varname>, and
+      <varname>ExtensionImagePolicy</varname> were added in version 254.</para>
+    </refsect2>
+    <refsect2>
+      <title>Slice Unit Objects</title>
+      <para><varname>ControlGroupId</varname> was added in version 251.</para>
+      <para><varname>MemoryZSwapMax</varname> was added in version 253.</para>
+      <para><varname>DelegateSubgroup</varname>,
+      <varname>DefaultStartupMemoryLow</varname>,
+      <varname>StartupMemoryLow</varname>,
+      <varname>StartupMemoryHigh</varname>,
+      <varname>StartupMemoryMax</varname>,
+      <varname>StartupMemorySwapMax</varname>,
+      <varname>StartupMemoryZSwapMax</varname>,
+      <varname>MemoryPressureWatch</varname>, and
+      <varname>MemoryPressureThresholdUSec</varname> were added in version 254.</para>
+    </refsect2>
+    <refsect2>
+      <title>Scope Unit Objects</title>
+      <para><varname>ControlGroupId</varname> was added in version 251.</para>
+      <para><varname>OOMPolicy</varname> and
+      <varname>MemoryZSwapMax</varname> were added in version 253.</para>
+      <para><varname>DelegateSubgroup</varname>,
+      <varname>DefaultStartupMemoryLow</varname>,
+      <varname>StartupMemoryLow</varname>,
+      <varname>StartupMemoryHigh</varname>,
+      <varname>StartupMemoryMax</varname>,
+      <varname>StartupMemorySwapMax</varname>,
+      <varname>StartupMemoryZSwapMax</varname>,
+      <varname>MemoryPressureWatch</varname>, and
+      <varname>MemoryPressureThresholdUSec</varname> were added in version 254.</para>
+    </refsect2>
+    <refsect2>
+      <title>Job Objects</title>
+      <para><varname>ActivationDetails</varname> was added in version 252.</para>
+    </refsect2>
+  </refsect1>
 </refentry>
diff --git a/tools/update-dbus-docs.py b/tools/update-dbus-docs.py
@@ -141,10 +141,16 @@ def print_interface(iface, *, prefix, file, print_boring, only_interface, declar
         print(f'''{prefix}}};''', file=file)
 
 def document_has_elem_with_text(document, elem, item_repr):
-    predicate = f".//{elem}" # [text() = 'foo'] doesn't seem supported :(
+    predicate = f".//{elem}[. = '{item_repr}']"
+
+    # Ignore mentions in the History section
+    history = document.find(".//refsect1[title = 'History']")
+    history_mentions = history.findall(predicate) if history else []
+
     for loc in document.findall(predicate):
-        if loc.text == item_repr:
-            return True
+        if loc in history_mentions:
+            continue
+        return True
     return False
 
 def check_documented(document, declarations, stats):