From 43b238f1c150c5dd9d8653f0a28e1ffad95d119d Mon Sep 17 00:00:00 2001 From: Frantisek Sumsal Date: Tue, 23 Jan 2024 13:06:55 +0100 Subject: [PATCH] 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 --- man/org.freedesktop.import1.xml | 12 +++--- man/org.freedesktop.login1.xml | 74 ++++++++++++++++---------------- man/org.freedesktop.machine1.xml | 10 ++--- man/org.freedesktop.oom1.xml | 6 +-- man/org.freedesktop.systemd1.xml | 36 +++++----------- tools/dbus_ignorelist | 46 ++++++++++---------- tools/update-dbus-docs.py | 15 ++++--- 7 files changed, 94 insertions(+), 105 deletions(-) diff --git a/man/org.freedesktop.import1.xml b/man/org.freedesktop.import1.xml index d981bc0d4b6..e230a69f4cc 100644 --- a/man/org.freedesktop.import1.xml +++ b/man/org.freedesktop.import1.xml @@ -131,9 +131,9 @@ node /org/freedesktop/import1 { - + - + @@ -169,7 +169,7 @@ node /org/freedesktop/import1 { be used to retrieve progress information about the transfer or to cancel it. The transfer identifier is a simple numeric identifier, the object path references an org.freedesktop.import1.Transfer object, see below. Listen for a - TransferRemoved signal for the transfer ID in order to detect when a transfer is + TransferRemoved() signal for the transfer ID in order to detect when a transfer is complete. The returned transfer object is useful to determine the current progress or log output of the ongoing import operation. @@ -220,11 +220,11 @@ node /org/freedesktop/import1 { Signals - The TransferNew signal is generated each time a new transfer is started with + The TransferNew() signal is generated each time a new transfer is started with the import, export or download calls described above. It carries the transfer ID and object path that have just been created. - The TransferRemoved signal is sent each time a transfer finishes, + The TransferRemoved() signal is sent each time a transfer finishes, is canceled or fails. It also carries the transfer ID and object path, followed by a string indicating the result of the operation, which is one of done (on success), canceled or failed. @@ -272,7 +272,7 @@ node /org/freedesktop/import1/transfer/_1 { - + diff --git a/man/org.freedesktop.login1.xml b/man/org.freedesktop.login1.xml index 9151926e64d..8b84f227ff1 100644 --- a/man/org.freedesktop.login1.xml +++ b/man/org.freedesktop.login1.xml @@ -428,23 +428,23 @@ node /org/freedesktop/login1 { - + - + - + - + - + - + - + - + - + @@ -726,14 +726,14 @@ node /org/freedesktop/login1 { Whenever the inhibition state or idle hint changes, PropertyChanged signals are sent out to which clients can subscribe. - The SessionNew, SessionRemoved, - UserNew, UserRemoved, SeatNew, and - SeatRemoved signals are sent each time a session is created or removed, a user + The SessionNew(), SessionRemoved(), + UserNew(), UserRemoved(), SeatNew(), and + SeatRemoved() signals are sent each time a session is created or removed, a user logs in or out, or a seat is added or removed. They each contain the ID of the object plus the object path. - The PrepareForShutdown, - PrepareForShutdownWithMetadata, and PrepareForSleep + The PrepareForShutdown(), + PrepareForShutdownWithMetadata(), and PrepareForSleep() signals are sent right before (with the argument true) or after (with the argument false) the system goes down for reboot/poweroff and suspend/hibernate, respectively. This may be used by applications to save data on disk, release memory, or do other jobs @@ -745,7 +745,7 @@ node /org/freedesktop/login1 { pair metadata fields. Currently it sends a type string which defines the type of shutdown. The type can be one of power-off, reboot, halt, kexec or soft-reboot. This signal is - sent first, followed by PrepareForShutdown (for backward compatibility). + sent first, followed by PrepareForShutdown() (for backward compatibility). @@ -788,8 +788,8 @@ node /org/freedesktop/login1 { for more information. The PreparingForShutdown and PreparingForSleep boolean - properties are true during the interval between the two PrepareForShutdown and - PrepareForSleep signals respectively. Note that these properties do not + properties are true during the interval between the two PrepareForShutdown() and + PrepareForSleep() signals respectively. Note that these properties do not send out PropertyChanged signals. The RebootParameter property shows the value set with the @@ -800,9 +800,9 @@ node /org/freedesktop/login1 { RebootToFirmwareSetup, RebootToBootLoaderMenu, and RebootToBootLoaderEntry are true when the resprective post-reboot operation was - selected with SetRebootToFirmwareSetup, - SetRebootToBootLoaderMenu, or - SetRebootToBootLoaderEntry. + selected with SetRebootToFirmwareSetup(), + SetRebootToBootLoaderMenu(), or + SetRebootToBootLoaderEntry(). The WallMessage and EnableWallMessages properties reflect the shutdown reason and wall message enablement switch which can be set with the @@ -847,15 +847,15 @@ node /org/freedesktop/login1 { the inhibits of the auto-selected sleep operation. SetRebootParameter() requires org.freedesktop.login1.set-reboot-parameter. - SetRebootToFirmwareSetup requires + SetRebootToFirmwareSetup() requires org.freedesktop.login1.set-reboot-to-firmware-setup. - SetRebootToBootLoaderMenu requires + SetRebootToBootLoaderMenu() requires org.freedesktop.login1.set-reboot-to-boot-loader-menu. - SetRebootToBootLoaderEntry requires + SetRebootToBootLoaderEntry() requires org.freedesktop.login1.set-reboot-to-boot-loader-entry. - ScheduleShutdown and CancelScheduledShutdown require + ScheduleShutdown() and CancelScheduledShutdown() require the same privileges (listed above) as the immediate poweroff/reboot/halt operations. Inhibit() is protected via one of @@ -1255,13 +1255,13 @@ node /org/freedesktop/login1/session/1 { - + - + - + - + @@ -1393,28 +1393,28 @@ node /org/freedesktop/login1/session/1 { Signals - The active session controller exclusively gets PauseDevice and - ResumeDevice events for any device it requested via + The active session controller exclusively gets PauseDevice() and + ResumeDevice() events for any device it requested via TakeDevice(). They notify the controller whenever a device is paused or resumed. A - device is never resumed if its session is inactive. Also note that PauseDevice + device is never resumed if its session is inactive. Also note that PauseDevice() signals are sent before the PropertyChanged signal for the - Active state. The inverse is true for ResumeDevice. A device + Active state. The inverse is true for ResumeDevice(). A device may remain paused for unknown reasons even though the Session is active. - A PauseDevice signal carries the major and minor numbers and a string describing the + A PauseDevice() signal carries the major and minor numbers and a string describing the type as arguments. force means the device was already paused by systemd-logind and the signal is only an asynchronous notification. pause means systemd-logind grants you a limited amount of time to pause the device. You must respond to this via PauseDeviceComplete(). This synchronous pausing mechanism is used for backwards-compatibility to VTs and systemd-logind is free to not make use of - it. It is also free to send a forced PauseDevice if you don't respond in a timely + it. It is also free to send a forced PauseDevice() if you don't respond in a timely manner (or for any other reason). gone means the device was unplugged from the system and you will no longer get any notifications about it. There is no need to call ReleaseDevice(). You may call TakeDevice() again if a new device is assigned the major+minor combination. - ResumeDevice is sent whenever a session is active and a device is + ResumeDevice() is sent whenever a session is active and a device is resumed. It carries the major/minor numbers as arguments and provides a new open file descriptor. You should switch to the new descriptor and close the old one. They are not guaranteed to have the same underlying open file descriptor in the kernel (except for a limited set of device types). @@ -1422,7 +1422,7 @@ node /org/freedesktop/login1/session/1 { Whenever Active or the idle state changes, PropertyChanged signals are sent out to which clients can subscribe. - Lock/Unlock is sent when the session is asked to be + Lock()/Unlock() is sent when the session is asked to be screen-locked/unlocked. A session manager of the session should listen to this signal and act accordingly. This signal is sent out as a result of the Lock() and Unlock() methods, respectively. @@ -1568,7 +1568,7 @@ node /org/freedesktop/login1/session/1 { HandleSuspendKeyLongPress, and HandleHibernateKeyLongPress were added in version 251. StopIdleSessionUSec was added in version 252. - PrepareForShutdownWithMetadata and + PrepareForShutdownWithMetadata() and CreateSessionWithPIDFD() were added in version 255. Sleep(), CanSleep(), diff --git a/man/org.freedesktop.machine1.xml b/man/org.freedesktop.machine1.xml index a748b7652d6..cc4e61d2d47 100644 --- a/man/org.freedesktop.machine1.xml +++ b/man/org.freedesktop.machine1.xml @@ -184,8 +184,6 @@ node /org/freedesktop/machine1 { - - @@ -284,9 +282,9 @@ node /org/freedesktop/machine1 { - + - + @@ -411,7 +409,7 @@ node /org/freedesktop/machine1 { host as arguments. CopyToMachine() does the opposite and copies files from a source directory on the host into a destination directory in the container. - CopyFromMachineWithFlags() and CopyToMachineWithFlags do the same but take an additional flags argument. + CopyFromMachineWithFlags() and CopyToMachineWithFlags() do the same but take an additional flags argument. RemoveImage() removes the image with the specified name. @@ -434,7 +432,7 @@ node /org/freedesktop/machine1 { Signals - MachineNew and MachineRemoved are sent whenever a new + MachineNew() and MachineRemoved() are sent whenever a new machine is registered or removed. These signals carry the machine name and the object path to the corresponding org.freedesktop.machine1.Machine interface (see below). diff --git a/man/org.freedesktop.oom1.xml b/man/org.freedesktop.oom1.xml index d7b2b9c5d85..1b549c347ca 100644 --- a/man/org.freedesktop.oom1.xml +++ b/man/org.freedesktop.oom1.xml @@ -59,14 +59,14 @@ node /org/freedesktop/oom1 { - + Methods - Killed signal is sent when any cgroup is killed by oomd. + Killed() signal is sent when any cgroup is killed by oomd. Note that more reasons will be added in the future, and the table below will be expanded accordingly. Killing reasons @@ -100,7 +100,7 @@ node /org/freedesktop/oom1 { History The Manager Object - Killed was added in version 252. + Killed() was added in version 252. diff --git a/man/org.freedesktop.systemd1.xml b/man/org.freedesktop.systemd1.xml index 5f1a5988a0c..fa2ebb6fe5b 100644 --- a/man/org.freedesktop.systemd1.xml +++ b/man/org.freedesktop.systemd1.xml @@ -617,20 +617,6 @@ node /org/freedesktop/systemd1 { - - - - - - - - - - - - - - @@ -997,19 +983,19 @@ node /org/freedesktop/systemd1 { - + - + - + - + - + - + - + @@ -1878,7 +1864,7 @@ node /org/freedesktop/systemd1 { enablement state (EnableUnitFiles(), DisableUnitFiles(), EnableUnitFilesWithFlags(), DisableUnitFilesWithFlags(), ReenableUnitFiles(), LinkUnitFiles(), - PresetUnitFiles, MaskUnitFiles, and similar) require + PresetUnitFiles(), MaskUnitFiles(), and similar) require org.freedesktop.systemd1.manage-unit-files. Operations which modify the exported environment (SetEnvironment(), UnsetEnvironment(), UnsetAndSetEnvironment()) require @@ -11563,7 +11549,7 @@ node /org/freedesktop/systemd1/unit/session_2d1_2escope { - + @@ -11786,7 +11772,7 @@ node /org/freedesktop/systemd1/unit/session_2d1_2escope { Signals - RequestStop is sent to the peer that is configured in the + RequestStop() is sent to the peer that is configured in the Controller property when systemd is requested to terminate the scope unit. A program registering a scope can use this to cleanly shut down the processes it added to the scope instead of letting systemd do it with the usual SIGTERM logic. @@ -11798,7 +11784,7 @@ node /org/freedesktop/systemd1/unit/session_2d1_2escope { All properties correspond directly with the matching properties of service units. Controller contains the bus name (unique or well-known) that is notified when - the scope unit is to be shut down via a RequestStop signal (see below). This is + the scope unit is to be shut down via a RequestStop() signal (see below). This is set when the scope is created. If not set, the scope's processes will terminated with SIGTERM directly. diff --git a/tools/dbus_ignorelist b/tools/dbus_ignorelist index d0c2150a7ff..71bdad8b573 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 008f7d4e19e..ce7161c5f14 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 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