The trailing dot is already added when generating the man page.

https://gitlab.freedesktop.org/NetworkManager/NetworkManager/-/merge_requests/439

Showcase nm_client_dbus_set_property().

Thereby, also print error messages and return an error if
the command fails.

Also, enable PolicyKit authentication (although, I think there are
some bugs with this still).

Previously, we would call the synchronous nm_client_networking_set_enabled()
method. There were 3 problems:

1) nmcli ignored the return value, that means, if the request failed with
  access denied it would just silently pretend that it succeeded.

2) nmcli first called nmc_start_polkit_agent_start_try(), but when
  invoking the synchronous method, the main context is busy and a
  polkit request cannot possibly be handled.

3) nm_client_networking_set_enabled() is deprecated.

Fix all of these, by calling the D-Bus method directly.

Policykit authentication requests are only handled partly. There
seems to be an unrelated race/bug. Now it works sometimes.

This is more a showcase for using nm_client_dbus_call(), than a
real use.

In this case, nmcli was mostly fine to just invoke the synchronous API
and not care about the problems that it had.

Still, replace it, and show the suggested alternative.

With 1.22, various synchronous functions for invoking D-Bus methods were
deprecated. The reason was that D-Bus is fundamentally asynchronous, and
providing synchronous API in NMClient is inherently wrong. That is
because NMClient essentially is a cache of the D-Bus API, and invoking
g_dbus_connection_call_sync() messes up the order of events from D-Bus.
In particular, when the synchronous function completes, the content of
the cache does not yet reflect the change.

Since they got deprecated, the question is with what to replace them.

Instead of adding a (e.g.) nm_client_networking_set_enabled_async()
for nm_client_networking_set_enabled(), just expect the user to call
D-Bus directly.

D-Bus itself defines a reasonable API, and with GDBusConnection it
is fine (and convenient) to just call D-Bus operations directly.
Often libraries try to abstract D-Bus by providing convenience
wrappers around D-Bus API. I think that often is wrong and unnecessary.

Note that libnm's NMClient does a lot more than just wrapping simple
D-Bus calls. It provides a complete client-side cache of the D-Bus
interface. As such, what libnm's NMClient does is more than simple
wrappers around D-Bus. NMClient is a reasonable thing to do.

However, it is unnecessary to add API like nm_client_networking_set_enabled_async()
that only calls g_dbus_connection_call(). Don't pretend that we would need such
trivial wrappers in libnm.

Instead, recommend to use g_dbus_connection_call(). Or alternatively,
the convenience wrappers nm_client_dbus_call() and
nm_client_dbus_set_property().