libcroesor: Document all missing elements

This is necessary to allow the gtk-doc check to not fail.

The gtk-doc check is run at the check step to verify that everything is
documented. This is useful to avoid forgetting documentation when
modifying the code.

Signed-off-by: Detlev Casanova <detlev.casanova@collabora.com>

libcroesor/backend-manager.c

@@ -19,6 +19,14 @@
 
 #include "backend-manager.h"
 
+/**
+ * SECTION:backend-manager
+ * @short_description: An implementation of #CsrPeerManager which manages a single peer: the daemon.
+ *
+ * See also #CsrBackendManager
+ *
+ * #backend-manager is available since 0.4.0
+ */
 
 static void            csr_backend_manager_peer_manager_init          (CsrPeerManagerInterface  *iface);
 static void            csr_backend_manager_dispose                    (GObject                  *object);

libcroesor/backend-manager.h

@@ -18,6 +18,13 @@
 
 G_BEGIN_DECLS
 
+/**
+ * CSR_TYPE_BACKEND_MANAGER:
+ *
+ * Retrieve the #CsrBackendMAnager type.
+ *
+ * Since: 0.2.0
+ */
 #define CSR_TYPE_BACKEND_MANAGER csr_backend_manager_get_type ()
 G_DECLARE_FINAL_TYPE (CsrBackendManager, csr_backend_manager, CSR,
                       BACKEND_MANAGER, GObject)

libcroesor/backend.c

@@ -22,9 +22,24 @@
 #include "libcroesor/vehicle-manager.h"
 #include "libcroesor/vehicle-service.h"
 
+/**
+ * SECTION:backend
+ * @short_description: Implementation of a backend
+ *
+ * A skeleton implementation of a backend for the vehicle device daemon.
+ * See also #CsrBackend
+ *
+ * #backend is available since 0.2.0
+ */
 
 /* These errors do not need to be registered with
  * g_dbus_error_register_error_domain() as they never go over the bus. */
+
+/**
+ * csr_backend_error_quark:
+ *
+ * Return a GQuark from the csr-backend-error-quark string
+ */
 GQuark
 csr_backend_error_quark (void)
 {

libcroesor/backend.h

@@ -43,6 +43,13 @@ typedef enum
   CSR_BACKEND_ERROR_VEHICLE_UNREGISTERED,
 } CsrBackendError;
 
+/**
+ * CSR_TYPE_BACKEND:
+ *
+ * Retrieve the #CsrBackend type.
+ *
+ * Since: 0.2.0
+ */
 #define CSR_TYPE_BACKEND csr_backend_get_type ()
 G_DECLARE_FINAL_TYPE (CsrBackend, csr_backend, CSR, BACKEND, CsrService)
 

libcroesor/clock.h

@@ -16,6 +16,15 @@
 
 G_BEGIN_DECLS
 
+/**
+ * SECTION:clock
+ * @short_description: Clock management function
+ *
+ * See also #CsrClockFunc
+ *
+ * #clock is available since 0.4.0
+ */
+
 /**
  * CsrClockFunc:
  * @user_data: user data to pass to the clock

libcroesor/docs/libcroesor-docs.sgml

 <?xml version="1.0"?>
 <!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.3//EN"
-               "http://www.oasis-open.org/docbook/xml/4.3/docbookx.dtd"
-[
-  <!ENTITY % local.common.attrib "xmlns:xi  CDATA  #FIXED 'http://www.w3.org/2003/XInclude'">
-  <!ENTITY % gtkdocentities SYSTEM "xml/gtkdocentities.ent">
-  %gtkdocentities;
-]>
+               "http://www.oasis-open.org/docbook/xml/4.3/docbookx.dtd">
 <book id="index" xmlns:xi="http://www.w3.org/2003/XInclude">
   <bookinfo>
-    <title>&package_name; Reference Manual</title>
-    <releaseinfo>
-      for &package_string;.
-      The latest version of this documentation can be found on-line at
-      <ulink role="online-location" url="http://[SERVER]/&package_name;/index.html">http://[SERVER]/&package_name;/</ulink>.
-    </releaseinfo>
+    <title>libcroesor Reference Manual</title>
   </bookinfo>
 
+  <xi:include href="overview.xml"/>
   <chapter>
-    <title>[Insert title here]</title>
+    <title>libcroesor APIs</title>
     <xi:include href="xml/backend.xml"/>
     <xi:include href="xml/backend-manager.xml"/>
     <xi:include href="xml/clock.xml"/>

libcroesor/docs/overview.xml

+<section xml:id="libcroesor-overview">
+  <title>libcroesor Overview</title>
+  <para>
+    Mail the maintainers (<email>rhosydd@apertis.org</email>)
+  </para>
+  <para>
+    libcroesor is a library for use within the Rhosydd daemon and its backends (both internal and external backends). It provides utility classes for implementing collections of attributes and zones in vehicles, and exposing them over D-Bus to be consumed. The vehicles exposed by Rhosydd backends are consumed by the Rhosydd daemon itself, which aggregates them and exposes them to applications.
+  </para>
+  <para>
+    Each backend exposes zero or more vehicles. The main interface for building a backend is the <ulink role="online-location" url="#CsrBackend">CsrBackend</ulink> class, which sets up the necessary D-Bus connection, and provides a <ulink role="online-location" url="#CsrVehicleManager">CsrVehicleManager</ulink> which the backend can use to expose its vehicles on the bus. Typically, the bulk of the implementation of a backend will be in building a class which implements <literal>RsdVehicle</literal> to expose the backend’s vehicle. The <ulink role="online-location" url="#CsrStaticVehicle">CsrStaticVehicle</ulink> class is provided as a basic implementation suitable for backends which need to expose vehicles with a fixed set of attributes whose values do not change over time.
+  </para>
+  <para>
+    The implementation of an <literal>RsdVehicle</literal> to expose attributes from physical components in a vehicle depends on how those components are exposed to the automotive domain. All Rhosydd backends run in the consumer entertainment (CE) domain so, typically, a Rhosydd backend will need to use the inter-domain connection to retrieve sensor data from, and to send actuator commands to, the automotive domain. These implementation details are vehicle-specific; hence all libcroesor and librhosydd can do is provide the <literal>RsdVehicle</literal> interface to implement.
+  </para>
+  <para>
+    Within the daemon, vehicles from the backends are aggregated by their IDs: if two backends expose a vehicle with the same ID, those two vehicles are exposed as a single aggregate vehicle by the backend. This means that multiple backends can be used to provide different attributes for the //same// vehicle, if that suits the architecture in the automotive domain. For example, one backend could expose all attributes which require communication over the vehicle’s CAN bus; and another backend could expose all attributes which are associated with hardware directly connected to the CE domain. If all these attributes are exposed on <literal>RsdVehicle</literal> objects with the same ID, they will be aggregated to form a single vehicle to be exposed to applications. This allows Rhosydd backends to be compartmentalised for security purposes, rather than requiring a monolithic backend which has access to all hardware and buses in the vehicle.
+  </para>
+  <para>
+    When two vehicles are aggregated, their zone hierarchies are combined to form an aggregate zone hierarchy which includes all zones from both vehicles. If the vehicles define the same zone, a single instance of that is present in the aggregate hierarchy (since a zone is a path and nothing more).
+  </para>
+  <para>
+    Their attribute lists are combined to form an aggregate attribute list: all the attributes for a given zone from both vehicles are included in the aggregate attribute list. If both vehicles define the same attribute in a given zone, that is an error and one or both of the backends providing those vehicles will be disconnected from the daemon. In future, the system may permit duplicate attributes to be defined, and would combine their values in the aggregate attribute list; so do not rely on the current semantics.
+  </para>
+  <para>
+    The daemon will forward signals from the backends to the aggregated vehicles, signalling updates to attributes and metadata.
+  </para>
+  <para>
+    The daemon will also apply security policy to the vehicles it exposes to applications, reducing the availability of a given attribute if an application is not permitted to access it. This is pending implementation, and its semantics will be defined more rigorously in future.
+  </para>
+</section>

libcroesor/peer-manager.c

@@ -16,6 +16,15 @@
 
 #include "peer-manager.h"
 
+/**
+ * SECTION:peer-manager
+ * @short_description: An object instance which implements #CsrPeerManagerInterface.
+ *
+ * See also #CsrPeerManager
+ *
+ * #peer-manager is available since 0.2.0
+ */
+
 G_DEFINE_INTERFACE (CsrPeerManager, csr_peer_manager, G_TYPE_OBJECT)
 
 static void
@@ -137,13 +146,12 @@ csr_peer_manager_ensure_peer_info_finish (CsrPeerManager  *peer_manager,
   //return g_steal_pointer (&retval);
 }
 
-/*
+/**
  * csr_peer_manager_check_authorization_async:
  * @peer_manager: a #CsrPeerManager
  * @sender: D-Bus unique name of the peer which is making a request
  * @connection: #GDBusConnection associated with @sender
  * @action_id: ID of the polkit action to check for authorisation
- * @details: populated #PolkitDetails object to pass to the authorisation check
  * @cancellable: (nullable): a #GCancellable, or %NULL
  * @callback: callback to call once the check is complete
  * @user_data: data to pass to @callback

libcroesor/peer-manager.h

@@ -24,7 +24,22 @@ G_BEGIN_DECLS
  *
  * Since: 0.4.0
  */
+/**
+ * CSR_TYPE_PEER_MANAGER:
+ *
+ * Retrieve the #CsrPeerManager type.
+ *
+ * Since: 0.2.0
+ */
 #define CSR_TYPE_PEER_MANAGER csr_peer_manager_get_type ()
+
+/**
+ * CsrPeerManager:
+ *
+ * An object instance which implements #CsrPeerManagerInterface.
+ *
+ * Since: 0.4.0
+ */
 G_DECLARE_INTERFACE (CsrPeerManager, csr_peer_manager, CSR,
                      PEER_MANAGER, GObject)
 

libcroesor/service.c

@@ -21,9 +21,23 @@
 #include "libcroesor/service.h"
 #include "libinternal/logging.h"
 
+/**
+ * SECTION:service
+ * @short_description: A skeleton implementation of a system service
+ *
+ * See also #CsrService
+ *
+ * #service is available since 0.2.0
+ */
 
 /* These errors do not need to be registered with
  * g_dbus_error_register_error_domain() as they never go over the bus. */
+
+/**
+ * csr_service_error_quark:
+ *
+ * Return a GQuark from the csr-service-error-quark string
+ */
 GQuark
 csr_service_error_quark (void)
 {

libcroesor/service.h

@@ -49,9 +49,26 @@ typedef enum
   CSR_SERVICE_ERROR_INVALID_ENVIRONMENT,
 } CsrServiceError;
 
+/**
+ * CSR_TYPE_SERVICE:
+ *
+ * Retrieve the #CsrService type.
+ *
+ * Since: 0.2.0
+ */
 #define CSR_TYPE_SERVICE csr_service_get_type ()
 G_DECLARE_DERIVABLE_TYPE (CsrService, csr_service, CSR, SERVICE, GObject)
 
+/**
+ * CsrServiceClass:
+ * @parent_class: the parent class.
+ * @get_main_option_entries: callback to get the main option entries.
+ * @startup_async: callback for startup async.
+ * @startup_finish: callback for startup finish.
+ * @shutdown: callback for shutdown.
+ *
+ * Probably does something awesome.
+ */
 struct _CsrServiceClass
 {
   GObjectClass parent_class;
@@ -67,12 +84,16 @@ struct _CsrServiceClass
                           GError             **error);
   void (*shutdown)       (CsrService          *service);
 
+  /*< private >*/
   gpointer padding[12];
 };
 
-CsrService *csr_service_new              (const gchar   *object_path,
+
+// This function has no implementation
+/*CsrService *csr_service_new              (const gchar   *object_path,
                                           const gchar   *translation_domain,
                                           const gchar   *summary);
+*/
 void        csr_service_add_option_group (CsrService    *self,
                                           GOptionGroup  *group);
 

libcroesor/static-vehicle.c

@@ -20,6 +20,14 @@
 #include "librhosydd/types.h"
 #include "librhosydd/vehicle.h"
 
+/**
+ * SECTION:static-vehicle
+ * @short_description: An implementation of #RsdVehicle.
+ *
+ * See also #CsrStaticVehicle
+ *
+ * #static-vehicle is available since 0.1.0
+ */
 
 static void csr_static_vehicle_vehicle_init (RsdVehicleInterface *iface);
 static void csr_static_vehicle_dispose      (GObject             *object);

libcroesor/static-vehicle.h

@@ -18,6 +18,13 @@
 
 G_BEGIN_DECLS
 
+/**
+ * CSR_TYPE_STATIC_VEHICLE:
+ *
+ * Retrieve the #CsrStaticVehicle type.
+ *
+ * Since: 0.2.0
+ */
 #define CSR_TYPE_STATIC_VEHICLE csr_static_vehicle_get_type ()
 G_DECLARE_FINAL_TYPE (CsrStaticVehicle, csr_static_vehicle, CSR,
                       STATIC_VEHICLE, GObject)

libcroesor/subscription-manager.c

@@ -17,6 +17,14 @@
 #include "librhosydd/subscription.h"
 #include "librhosydd/vehicle.h"
 
+/**
+ * SECTION:subscription-manager
+ * @short_description: A manager object which stores the sets of subscriptions
+ *
+ * See also #CsrSubscriptionManager
+ *
+ * #subscription-manager is available since 0.2.0
+ */
 
 static void csr_subscription_manager_dispose (GObject *object);
 

libcroesor/subscription-manager.h

@@ -18,6 +18,13 @@
 
 G_BEGIN_DECLS
 
+/**
+ * CSR_TYPE_SUBSCRIPTION_MANAGER:
+ *
+ * Retrieve the #CsrSubscriptionManager type.
+ *
+ * Since: 0.2.0
+ */
 #define CSR_TYPE_SUBSCRIPTION_MANAGER csr_subscription_manager_get_type ()
 G_DECLARE_FINAL_TYPE (CsrSubscriptionManager, csr_subscription_manager, CSR,
                       SUBSCRIPTION_MANAGER, GObject)

libcroesor/vehicle-manager.c

@@ -16,6 +16,14 @@
 #include "libinternal/logging.h"
 #include "librhosydd/vehicle.h"
 
+/**
+ * SECTION:vehicle-manager
+ * @short_description: A manager object which stores a set of #RsdVehicles
+ *
+ * See also #CsrVehicleManager
+ *
+ * #vehicle-manager is available since 0.1.0
+ */
 
 static void csr_vehicle_manager_dispose      (GObject      *object);
 

libcroesor/vehicle-manager.h

@@ -18,6 +18,13 @@
 
 G_BEGIN_DECLS
 
+/**
+ * CSR_TYPE_VEHICLE_MANAGER:
+ *
+ * Retrieve the #CsrVehicleManager type.
+ *
+ * Since: 0.2.0
+ */
 #define CSR_TYPE_VEHICLE_MANAGER csr_vehicle_manager_get_type ()
 G_DECLARE_FINAL_TYPE (CsrVehicleManager, csr_vehicle_manager, CSR,
                       VEHICLE_MANAGER, GObject)

libcroesor/vehicle-service.c

@@ -26,6 +26,15 @@
 #include "librhosydd/vehicle-interface-generated.c"
 #include "librhosydd/vehicle.h"
 
+/**
+ * SECTION:vehicle-service
+ * @short_description: An implementation of a D-Bus interface to expose a collection of vehicles on
+ * the bus.
+ *
+ * See also #CsrVehicleService
+ *
+ * #vehicle-service is available since 0.1.0
+ */
 
 static void csr_vehicle_service_constructed  (GObject *object);
 static void csr_vehicle_service_dispose      (GObject      *object);

libcroesor/vehicle-service.h

@@ -21,6 +21,13 @@
 
 G_BEGIN_DECLS
 
+/**
+ * CSR_TYPE_VEHICLE_SERVICE:
+ *
+ * Retrieve the #CsrVehicleService type.
+ *
+ * Since: 0.2.0
+ */
 #define CSR_TYPE_VEHICLE_SERVICE csr_vehicle_service_get_type ()
 G_DECLARE_FINAL_TYPE (CsrVehicleService, csr_vehicle_service, CSR, VEHICLE_SERVICE,
                       GObject)

libcroesor/version.h.in

@@ -8,6 +8,15 @@
  * file, You can obtain one at http://mozilla.org/MPL/2.0/.
  */
 
+/**
+ * SECTION:version
+ * @short_description: Macros to manage the version
+ *
+ * Provides different macros to retrieve and check libcroesor version.
+ *
+ * #version is available since 0.1.0
+ */
+
 #ifndef CSR_VERSION_H
 #define CSR_VERSION_H