System services documentation (#814)

* Documentation fixes
* Fix SystemService documentation
* Add an overview of the system services API
* Fix services and sockets documentation formatting
* Reduce services and sockets nesting

.yardopts

@@ -1 +1 @@
---no-private --markup markdown --protected library/*/src/**/*.rb --readme README.md --output-dir ./doc/autodocs - library/cwm/doc/CWM.md library/systemd/doc/services_and_sockets.md
+--no-private --markup markdown --protected library/*/src/**/*.rb --readme README.md --output-dir ./doc/autodocs - library/cwm/doc/CWM.md library/systemd/doc/services_and_sockets.md library/system/doc/system_services.md

library/system/doc/system_services.md

@@ -0,0 +1,36 @@
+# System Services Library
+
+The system services library offers an API to interact with system services, allowing the user to
+perform typical operations like querying the services, starting or stopping them, etc.
+
+The set of classes which are included in this library can be divided into:
+
+* A high level API which offers some abstractions on top of Systemd.
+* A low level one to talk closely to Systemd units (including services and sockets).
+
+Additionally, a widget that can be used in YaST modules (like yast2-dns-server) is included.
+
+## High Level API
+
+The high level API is composed by these classes:
+
+* {Yast2::SystemService}: represents a service (like `cups` or `dbus`) from a high level point of
+  view. Systemd concepts like *units* or *sockets* are abstracted by this class.
+* {Yast2::CompoundService}: groups a set of related services that might be handled together.
+  Think, for instance, about `iscsi`, `iscsid` and `iscsiuio` services in `yast2-iscsi-client`.
+  This class offers basically the same API than {Yast2::SystemService}.
+
+## Low Level API
+
+The low level API can be more convenient in some situations and it is basically composed of a set of
+classes that map to Systemd concepts: {Yast2::Systemd::Unit}, {Yast2::Systemd::Service},
+{Yast2::Systemd::Socket} and {Yast2::Systemd::Target}.
+
+## Service Widget
+
+Additionally to the classes to interact with system services, this library offers a widget which
+allows the user to decide how (and when) a service should be started. It is meant to be used by
+modules which configure a given service (like `yast2-dns-server` or `yast2-iscsi-client`).
+
+See {Yast2::ServiceWidget} for the widget documentation and {CWM::ServiceWidget} for the CWM
+wrapper.

library/systemd/doc/services_and_sockets.md

@@ -1,35 +1,45 @@
 # Services and Sockets
 
-In systemd, it might happen that a single service is managed by a set of units, for example when a service is able to be activated via socket, path, timer, etc. In such cases, systemd works with a service unit (e.g., cups.service) and also with a socket (or path, timer, etc) unit (e.g., cups.socket).
+In systemd, it might happen that a single service is managed by a set of units, for example when a
+service is able to be activated via socket, path, timer, etc. In such cases, systemd works with a
+service unit (e.g., cups.service) and also with a socket (or path, timer, etc) unit (e.g.,
+cups.socket).
 
-When a service is configured by using YaST (e.g., with the Services Manager), all units related to each service must be taken into account. For example, when a service is stopped, the socket associated to such service should be also stopped. Otherwise, the sevice could be automatically activated again via its socket.
+When a service is configured by using YaST (e.g., with the Services Manager), all units related to
+each service must be taken into account. For example, when a service is stopped, the socket
+associated to such service should be also stopped. Otherwise, the sevice could be automatically
+activated again via its socket.
 
-This file describes a new class (named {Yast2::SystemService}) to work with the service and its associated socket as a whole. The main goal of this new class is to perform actions over both, the service and the socket, when it is required.
+This file extends the {Yast2::SystemService} class documentation describing how it works with the
+service and its associated socket as a whole. The main goal of this new class is to perform actions
+over both, the service and the socket, when it is required.
 
 ## {Yast2::SystemService} class
 
-This class is intended to represent a service from a high level point of view. It will offer an API to:
+This class is intended to represent a service from a high level point of view. It will offer an API
+to:
 
 * ask for service properties (e.g., is active, its state, start mode, etc)
-* perform "in memory" actions (start, stop, restart or reload) and change its start mode (on boot, on demand or manually)
+* perform "in memory" actions (start, stop, restart or reload) and change its start mode (on boot,
+  on demand or manually)
 * apply all changes in the "real system"
 
-One goal in this class is to offer an agnostic API. At this moment it uses Systemd in low levels layers, but in future this could change and the API should remain as much as possible.
+One goal in this class is to offer an agnostic API. At this moment it uses Systemd in low levels
+layers, but in future this could change and the API should remain as much as possible.
 
-### Actions over Systemd units
+## Actions over Systemd units
 
-The following table describes the actions to perform over a systemd service and its associated socket (if any) when we try to start, stop, restart or reload a `SystemService`.
+The following table describes the actions to perform over a systemd service and its associated
+socket (if any) when we try to start, stop, restart or reload a `SystemService`.
 
+| Status                   | Start                                          | Stop                    | Restart                                                                    | Reload                                            |
+| ---                      | ---                                            | ---                     | ---                                                                        | ---                                               |
+| Only socket running      | nothing                                        | stop socket             | stop socket and start service/socket (depending on start mode)             | nothing                                           |
+| Only service running     | nothing                                        | stop service            | stop service and start service/socket (depending on start mode)            | reload service (if it support, otherwise restart) |
+| Socket & Service running | nothing                                        | stop service and socket | stop service and socket and start service/socket (depending on start mode) | reload service (if it support, otherwise restart) |
+| Nothing runs             | start service/socket (depending on start mode) | nothing                 | start service/socket (depending on start mode)                             | start service/socket (depending on start mode)    |
 
-| Status | Start | Stop | Restart | Reload |
-|---|---|---|---|---|
-| Only socket running | nothing | stop socket | stop socket and start service/socket (depending on start mode) | nothing |
-| Only service running | nothing  | stop service  | stop service and start service/socket (depending on start mode) | reload service (if it support, otherwise restart) |
-| Socket & Service running | nothing | stop service and socket | stop service and socket and start service/socket (depending on start mode) | reload service (if it support, otherwise restart) |
-| Nothing runs | start service/socket (depending on start mode) | nothing | start service/socket (depending on start mode) | start service/socket (depending on start mode) |
-
-
-### Detailed actions
+## Detailed actions
 
 Here each `SystemService` action is decribed in a more detailed way.
 
@@ -52,27 +62,23 @@ First of all, we are going to consider that a `SystemService` is stopped/running
 
 ### `#stop`
 
-* Goal
-  * service is stopped (see [1])
+* Goal: service is stopped (see [1])
 
 * Actions
   * stops systemd socket if it is running
   * stops systemd service if it is running
 
 ### `#restart`
 
-* Goal
-  * service is stopped (see [1]) and started again (see [2])
+* Goal: service is stopped (see [1]) and started again (see [2])
 
 * Actions
   * calls to "stop service action" (see stop section) if the service is running (see [2])
   * calls to "start service action" (see start section)
 
 ### `#reload`
 
-* Goal
-  * service is reloaded or restarted or started
-
+* Goal: service is reloaded or restarted or started
 * Actions
   * when the service supports reload
     * and start mode is `on demand`

library/systemd/src/lib/yast2/compound_service.rb

@@ -51,7 +51,7 @@ def initialize(*services)
 
     # Saves all services
     #
-    # @see {Yast2::SystemService#save}
+    # @see Yast2::SystemService#save
     #
     # @return [Boolean] true if all services were correctly saved; false otherwise
     def save(keep_state: false)
@@ -79,7 +79,7 @@ def currently_active?
 
     # Whether any service supports reload
     #
-    # @see {Yast2::SystemService#support_reload?}
+    # @see Yast2::SystemService#support_reload?
     #
     # @return [Boolean]
     def support_reload?
@@ -92,7 +92,7 @@ def support_reload?
     # service supports :on_demand too, the possible start modes will the
     # all of them: :on_boot, on_demand and :manual.
     #
-    # @see {Yast2::SystemService#start_modes}
+    # @see Yast2::SystemService#start_modes
     #
     # @return [Array<Symbol>] start modes (:on_boot, :on_demand, :manual)
     def start_modes
@@ -101,7 +101,7 @@ def start_modes
 
     # Keywords that can be used to search for involved underlying units
     #
-    # @see {Yast2::SystemService#keywords}
+    # @see Yast2::SystemService#keywords
     #
     # @return [Array<String>]
     def keywords
@@ -176,7 +176,7 @@ def start_mode
     #
     # @note It offers and additional start mode `:inconsistent` that is not in {Yast2::SystemService}
     #
-    # @param [Symbol] new start mode (e.g., :on_boot, :on_demand, :manual, :inconsistent)
+    # @param configuration [Symbol] new start mode (e.g., :on_boot, :on_demand, :manual, :inconsistent)
     def start_mode=(configuration)
       if !AUTOSTART_OPTIONS.include?(configuration)
         raise ArgumentError, "Invalid parameter #{configuration.inspect}"

library/systemd/src/lib/yast2/system_service.rb

@@ -32,7 +32,7 @@ module Yast2
   # See also {file:library/systemd/doc/services_and_sockets.md}.
   #
   # @note All changes performed over an object of this class are not applied into the
-  # underlying system until the {#save} method is called.
+  #   underlying system until the {#save} method is called.
   #
   # @example Enabling a service
   #   cups = SystemService.find("cups")

library/systemd/src/lib/yast2/systemd/unit_properties.rb

@@ -8,7 +8,7 @@ class UnitProperties < OpenStruct
 
       SUPPORTED_STATES = %w(enabled disabled).freeze
 
-      # Values of {#active_state} fow which we consider a unit "active".
+      # Values of `#active_state` fow which we consider a unit "active".
       #
       # systemctl.c:check_unit_active uses (active, reloading)
       # For bsc#884756 we also consider "activating" to be active.