From fa6ea8095855696cf14cb65214020cdcdee79d6b Mon Sep 17 00:00:00 2001
From: Lennart Poettering <lennart@poettering.net>
Date: Fri, 19 Apr 2024 15:25:43 +0200
Subject: [PATCH] man: document the last remaining bits of the hostnamed D-Bus
 interface

---
 man/org.freedesktop.hostname1.xml | 34 ++++++++++++++++++-------------
 1 file changed, 20 insertions(+), 14 deletions(-)

diff --git a/man/org.freedesktop.hostname1.xml b/man/org.freedesktop.hostname1.xml
index 61d9831ca6b..d16ae9ab1c2 100644
--- a/man/org.freedesktop.hostname1.xml
+++ b/man/org.freedesktop.hostname1.xml
@@ -108,20 +108,6 @@ node /org/freedesktop/hostname1 {
 };
     </programlisting>
 
-    <!--method GetHardwareSerial is not documented!-->
-
-    <!--property OperatingSystemSupportEnd is not documented!-->
-
-    <!--property HardwareVendor is not documented!-->
-
-    <!--property HardwareModel is not documented!-->
-
-    <!--property FirmwareVersion is not documented!-->
-
-    <!--property FirmwareVendor is not documented!-->
-
-    <!--property FirmwareDate is not documented!-->
-
     <!--Autogenerated cross-references for systemd.directives, do not edit-->
 
     <variablelist class="dbus-interface" generated="True" extra-ref="org.freedesktop.hostname1"/>
@@ -299,6 +285,22 @@ node /org/freedesktop/hostname1 {
     <constant>UINT32_MAX</constant> otherwise. See <citerefentry project="man-pages"><refentrytitle>vsock</refentrytitle><manvolnum>7</manvolnum></citerefentry> for
     details.</para>
 
+    <para><varname>OperatingSystemSupportEnd</varname> exposes when the OS' vendor support ends, if this
+    information is known. It's an unsigned 64bit value, in µs since the UNIX epoch, UTC. If this information
+    is not known carries the value 2^64-1, i.e. <constant>UINT64_MAX</constant>.</para>
+
+    <para><varname>HardwareVendor</varname> and <varname>HardwareModel</varname> expose information about the
+    vendor of the hardware of the system. If no such information can be determined these properties are set
+    to empty strings.</para>
+
+    <para><varname>FirmwareVersion</varname> and <varname>FirmwareVendor</varname> expose information about
+    the system's firmware, i.e. a version string and a vendor name. If no such information can be determined
+    these properties are set to empty strings.</para>
+
+    <para><varname>FirmwareDate</varname> exposes the firmware build date, if that information is known. It's
+    an unsigned 64bit value, in µs since the UNIX epoch, UTC. If not known
+    <constant>UNIT64_MAX</constant>.</para>
+
     <refsect2>
       <title>Methods</title>
 
@@ -333,6 +335,10 @@ node /org/freedesktop/hostname1 {
       requires root privileges, and this method allows access to unprivileged clients through the polkit
       framework.</para>
 
+      <para><function>GetHardwareSerial()</function> returns the "hardware serial" as exposed by the kernel
+      based on DMI information. Reading the file directly requires root privileges, and this method allows
+      access to unprivileged clients through the polkit framework.</para>
+
       <para><function>Describe()</function> returns a JSON representation of all properties in one.</para>
     </refsect2>