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
This also adds an ignore list, which currently contains the whole API as of
version 250, since that's the base we used for dbus interfaces.
See d9d2d16aea
When executed in test mode, "OUTDATED" is appropriate. But when executed
to actually update the text, after the tool executes, those pages are the
opposite, not outdated.
668b3a42fe allowed update-dbus-docs.py to start
running on Cent OS 8 (instead of skipping). But subprocess.check_output()'s
text argument didn't exist until Python 3.7 and C8 is still running
Python 3.6. Use universal_newlines instead for backwards compatibility.
Very old versions of meson did not include the subdirectory name in the
target name, so we started adding various "top-level" custom targets in
subdirectories. This was nice because the main meson.build file wasn't
as cluttered. But then meson started including the subdir name in the
target name. So let's move the definition to the root so we can have all
targets named uniformly.
So far the units there were being documented had only one custom interface.
But for the pid1 case, something more flexibile is needed. So let's add
an annotation in the page what we want to print, and filter in the generator.
Compares to gdbus output, the values of properties are replaced by ellipses.
For arrays and strings, the outer markers are kept. This is obviously also told
by the type string, but it seems a bit easier to read this way.
For any elements which are undocumented, a comment is inserted in sources.
"Undocumented" means that the expected element was not found. This might
require some adjustments if I missed some markup types.
Invocation is manual:
$ tools/update-dbus-docs.py tools/update-dbus-docs.py man/org.freedesktop.login1.xml
$ tools/update-dbus-docs.py tools/update-dbus-docs.py man/org.freedesktop.resolve1.xml
$ tools/update-dbus-docs.py tools/update-dbus-docs.py man/org.freedesktop.systemd1.xml
...
If some object is not found on the bus, the existing output is retained. So the
user needs to make sure that the appropriate objects have been instantiated
before calling this. We don't change the dbus interface very often, so I think
this manual mode is OK as a starting point. Making this fully automatic later
would be nice of course.
