man: suffix signals with ()

Since signals can take arguments, let's suffix them with () as we
already do with functions. To make sure we remain consistent, make the
`update-dbus-docs.py` script check & fix any occurrences where this is
not the case.

Resolves: #31002

2 files changed, 33 insertions, 28 deletions

diff --git a/tools/dbus_ignorelist b/tools/dbus_ignorelist
index d0c2150a7f..71bdad8b57 100644
--- a/tools/dbus_ignorelist
+++ b/tools/dbus_ignorelist
@@ -82,12 +82,12 @@ org.freedesktop.import1.Manager.ImportTar()
 org.freedesktop.import1.Manager.ListTransfers()
 org.freedesktop.import1.Manager.PullRaw()
 org.freedesktop.import1.Manager.PullTar()
-org.freedesktop.import1.Manager.TransferNew
-org.freedesktop.import1.Manager.TransferRemoved
+org.freedesktop.import1.Manager.TransferNew()
+org.freedesktop.import1.Manager.TransferRemoved()
 org.freedesktop.import1.Transfer.Cancel()
 org.freedesktop.import1.Transfer.Id
 org.freedesktop.import1.Transfer.Local
-org.freedesktop.import1.Transfer.LogMessage
+org.freedesktop.import1.Transfer.LogMessage()
 org.freedesktop.import1.Transfer.Progress
 org.freedesktop.import1.Transfer.Remote
 org.freedesktop.import1.Transfer.Type
@@ -168,8 +168,8 @@ org.freedesktop.login1.Manager.NCurrentSessions
 org.freedesktop.login1.Manager.OnExternalPower
 org.freedesktop.login1.Manager.PowerOff()
 org.freedesktop.login1.Manager.PowerOffWithFlags()
-org.freedesktop.login1.Manager.PrepareForShutdown
-org.freedesktop.login1.Manager.PrepareForSleep
+org.freedesktop.login1.Manager.PrepareForShutdown()
+org.freedesktop.login1.Manager.PrepareForSleep()
 org.freedesktop.login1.Manager.PreparingForShutdown
 org.freedesktop.login1.Manager.PreparingForSleep
 org.freedesktop.login1.Manager.Reboot()
@@ -184,10 +184,10 @@ org.freedesktop.login1.Manager.RuntimeDirectoryInodesMax
 org.freedesktop.login1.Manager.RuntimeDirectorySize
 org.freedesktop.login1.Manager.ScheduleShutdown()
 org.freedesktop.login1.Manager.ScheduledShutdown
-org.freedesktop.login1.Manager.SeatNew
-org.freedesktop.login1.Manager.SeatRemoved
-org.freedesktop.login1.Manager.SessionNew
-org.freedesktop.login1.Manager.SessionRemoved
+org.freedesktop.login1.Manager.SeatNew()
+org.freedesktop.login1.Manager.SeatRemoved()
+org.freedesktop.login1.Manager.SessionNew()
+org.freedesktop.login1.Manager.SessionRemoved()
 org.freedesktop.login1.Manager.SessionsMax
 org.freedesktop.login1.Manager.SetRebootParameter()
 org.freedesktop.login1.Manager.SetRebootToBootLoaderEntry()
@@ -204,8 +204,8 @@ org.freedesktop.login1.Manager.TerminateSession()
 org.freedesktop.login1.Manager.TerminateUser()
 org.freedesktop.login1.Manager.UnlockSession()
 org.freedesktop.login1.Manager.UnlockSessions()
-org.freedesktop.login1.Manager.UserNew
-org.freedesktop.login1.Manager.UserRemoved
+org.freedesktop.login1.Manager.UserNew()
+org.freedesktop.login1.Manager.UserRemoved()
 org.freedesktop.login1.Manager.UserStopDelayUSec
 org.freedesktop.login1.Manager.WallMessage
 org.freedesktop.login1.Seat.ActivateSession()
@@ -237,14 +237,14 @@ org.freedesktop.login1.Session.Lock
 org.freedesktop.login1.Session.Lock()
 org.freedesktop.login1.Session.LockedHint
 org.freedesktop.login1.Session.Name
-org.freedesktop.login1.Session.PauseDevice
+org.freedesktop.login1.Session.PauseDevice()
 org.freedesktop.login1.Session.PauseDeviceComplete()
 org.freedesktop.login1.Session.ReleaseControl()
 org.freedesktop.login1.Session.ReleaseDevice()
 org.freedesktop.login1.Session.Remote
 org.freedesktop.login1.Session.RemoteHost
 org.freedesktop.login1.Session.RemoteUser
-org.freedesktop.login1.Session.ResumeDevice
+org.freedesktop.login1.Session.ResumeDevice()
 org.freedesktop.login1.Session.Scope
 org.freedesktop.login1.Session.Seat
 org.freedesktop.login1.Session.Service
@@ -343,8 +343,8 @@ org.freedesktop.machine1.Manager.GetMachineUIDShift()
 org.freedesktop.machine1.Manager.KillMachine()
 org.freedesktop.machine1.Manager.ListImages()
 org.freedesktop.machine1.Manager.ListMachines()
-org.freedesktop.machine1.Manager.MachineNew
-org.freedesktop.machine1.Manager.MachineRemoved
+org.freedesktop.machine1.Manager.MachineNew()
+org.freedesktop.machine1.Manager.MachineRemoved()
 org.freedesktop.machine1.Manager.MapFromMachineGroup()
 org.freedesktop.machine1.Manager.MapFromMachineUser()
 org.freedesktop.machine1.Manager.MapToMachineGroup()
@@ -653,8 +653,8 @@ org.freedesktop.systemd1.Manager.InitRDUnitsLoadFinishTimestamp
 org.freedesktop.systemd1.Manager.InitRDUnitsLoadFinishTimestampMonotonic
 org.freedesktop.systemd1.Manager.InitRDUnitsLoadStartTimestamp
 org.freedesktop.systemd1.Manager.InitRDUnitsLoadStartTimestampMonotonic
-org.freedesktop.systemd1.Manager.JobNew
-org.freedesktop.systemd1.Manager.JobRemoved
+org.freedesktop.systemd1.Manager.JobNew()
+org.freedesktop.systemd1.Manager.JobRemoved()
 org.freedesktop.systemd1.Manager.KExec()
 org.freedesktop.systemd1.Manager.KExecWatchdogUSec
 org.freedesktop.systemd1.Manager.KernelTimestamp
@@ -696,7 +696,7 @@ org.freedesktop.systemd1.Manager.Reload()
 org.freedesktop.systemd1.Manager.ReloadOrRestartUnit()
 org.freedesktop.systemd1.Manager.ReloadOrTryRestartUnit()
 org.freedesktop.systemd1.Manager.ReloadUnit()
-org.freedesktop.systemd1.Manager.Reloading
+org.freedesktop.systemd1.Manager.Reloading()
 org.freedesktop.systemd1.Manager.ResetFailed()
 org.freedesktop.systemd1.Manager.ResetFailedUnit()
 org.freedesktop.systemd1.Manager.RestartUnit()
@@ -717,7 +717,7 @@ org.freedesktop.systemd1.Manager.StartTransientUnit()
 org.freedesktop.systemd1.Manager.StartUnit()
 org.freedesktop.systemd1.Manager.StartUnitReplace()
 org.freedesktop.systemd1.Manager.StartUnitWithFlags()
-org.freedesktop.systemd1.Manager.StartupFinished
+org.freedesktop.systemd1.Manager.StartupFinished()
 org.freedesktop.systemd1.Manager.StopUnit()
 org.freedesktop.systemd1.Manager.Subscribe()
 org.freedesktop.systemd1.Manager.SwitchRoot()
@@ -726,10 +726,10 @@ org.freedesktop.systemd1.Manager.Tainted
 org.freedesktop.systemd1.Manager.ThawUnit()
 org.freedesktop.systemd1.Manager.TimerSlackNSec
 org.freedesktop.systemd1.Manager.TryRestartUnit()
-org.freedesktop.systemd1.Manager.UnitFilesChanged
-org.freedesktop.systemd1.Manager.UnitNew
+org.freedesktop.systemd1.Manager.UnitFilesChanged()
+org.freedesktop.systemd1.Manager.UnitNew()
 org.freedesktop.systemd1.Manager.UnitPath
-org.freedesktop.systemd1.Manager.UnitRemoved
+org.freedesktop.systemd1.Manager.UnitRemoved()
 org.freedesktop.systemd1.Manager.UnitsLoadFinishTimestamp
 org.freedesktop.systemd1.Manager.UnitsLoadFinishTimestampMonotonic
 org.freedesktop.systemd1.Manager.UnitsLoadStartTimestamp
@@ -1078,7 +1078,7 @@ org.freedesktop.systemd1.Scope.MemoryLow
 org.freedesktop.systemd1.Scope.MemoryMax
 org.freedesktop.systemd1.Scope.MemoryMin
 org.freedesktop.systemd1.Scope.MemorySwapMax
-org.freedesktop.systemd1.Scope.RequestStop
+org.freedesktop.systemd1.Scope.RequestStop()
 org.freedesktop.systemd1.Scope.RestartKillSignal
 org.freedesktop.systemd1.Scope.RestrictNetworkInterfaces
 org.freedesktop.systemd1.Scope.Result
diff --git a/tools/update-dbus-docs.py b/tools/update-dbus-docs.py
index 008f7d4e19..ce7161c5f1 100755
--- a/tools/update-dbus-docs.py
+++ b/tools/update-dbus-docs.py
@@ -152,12 +152,17 @@ def check_documented(document, declarations, stats, interface, missing_version):
         stats['total'] += len(items)
 
         for item in items:
-            if klass == 'method':
+            if klass in ('method', 'signal'):
                 elem = 'function'
                 item_repr = f'{item}()'
-            elif klass == 'signal':
-                elem = 'function'
-                item_repr = item
+
+                # Find all functions/signals in <function> elements that are not
+                # suffixed with '()' and fix them
+                for section in sections:
+                    element = section.find(f".//{elem}[. = '{item}']")
+                    if element is not None:
+                        element.text = item_repr
+
             elif klass == 'property':
                 elem = 'varname'
                 item_repr = item
@@ -259,7 +264,7 @@ def subst_output(document, programlisting, stats, missing_version):
                 variablelist = etree.Element("variablelist")
                 variablelist.attrib['class'] = 'dbus-'+decl_type
                 variablelist.attrib['generated'] = 'True'
-                if decl_type == 'method' :
+                if decl_type in ('method', 'signal'):
                     variablelist.attrib['extra-ref'] = declaration + '()'
                 else:
                     variablelist.attrib['extra-ref'] = declaration