From a313d3f251e0c918f394c6ebd08e401c9fb446a9 Mon Sep 17 00:00:00 2001
From: Detlev Casanova <detlev.casanova@collabora.com>
Date: Wed, 10 Aug 2022 16:50:56 -0400
Subject: [PATCH] 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 | 8 ++++++++
libcroesor/backend-manager.h | 7 +++++++
libcroesor/backend.c | 15 ++++++++++++++
libcroesor/backend.h | 7 +++++++
libcroesor/clock.h | 9 +++++++++
libcroesor/docs/libcroesor-docs.sgml | 17 ++++------------
libcroesor/docs/overview.xml | 30 ++++++++++++++++++++++++++++
libcroesor/peer-manager.c | 12 +++++++++--
libcroesor/peer-manager.h | 15 ++++++++++++++
libcroesor/service.c | 14 +++++++++++++
libcroesor/service.h | 23 ++++++++++++++++++++-
libcroesor/static-vehicle.c | 8 ++++++++
libcroesor/static-vehicle.h | 7 +++++++
libcroesor/subscription-manager.c | 8 ++++++++
libcroesor/subscription-manager.h | 7 +++++++
libcroesor/vehicle-manager.c | 8 ++++++++
libcroesor/vehicle-manager.h | 7 +++++++
libcroesor/vehicle-service.c | 9 +++++++++
libcroesor/vehicle-service.h | 7 +++++++
libcroesor/version.h.in | 9 +++++++++
20 files changed, 211 insertions(+), 16 deletions(-)
create mode 100644 libcroesor/docs/overview.xml
diff --git a/libcroesor/backend-manager.c b/libcroesor/backend-manager.c
index 65787b1..4b97e96 100644
--- a/libcroesor/backend-manager.c
+++ b/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);
diff --git a/libcroesor/backend-manager.h b/libcroesor/backend-manager.h
index 90a3ae3..66ae995 100644
--- a/libcroesor/backend-manager.h
+++ b/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)
diff --git a/libcroesor/backend.c b/libcroesor/backend.c
index f6294fb..72f42cb 100644
--- a/libcroesor/backend.c
+++ b/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)
{
diff --git a/libcroesor/backend.h b/libcroesor/backend.h
index 5468dc5..f619dec 100644
--- a/libcroesor/backend.h
+++ b/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)
diff --git a/libcroesor/clock.h b/libcroesor/clock.h
index c64b29a..3f3d87f 100644
--- a/libcroesor/clock.h
+++ b/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
diff --git a/libcroesor/docs/libcroesor-docs.sgml b/libcroesor/docs/libcroesor-docs.sgml
index 2e34b2d..f8aa3cc 100644
--- a/libcroesor/docs/libcroesor-docs.sgml
+++ b/libcroesor/docs/libcroesor-docs.sgml
@@ -1,23 +1,14 @@
<?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"/>
diff --git a/libcroesor/docs/overview.xml b/libcroesor/docs/overview.xml
new file mode 100644
index 0000000..3130267
--- /dev/null
+++ b/libcroesor/docs/overview.xml
@@ -0,0 +1,30 @@
+<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>
diff --git a/libcroesor/peer-manager.c b/libcroesor/peer-manager.c
index d68d16b..0ad659b 100644
--- a/libcroesor/peer-manager.c
+++ b/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
diff --git a/libcroesor/peer-manager.h b/libcroesor/peer-manager.h
index e4775ad..3f5e933 100644
--- a/libcroesor/peer-manager.h
+++ b/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)
diff --git a/libcroesor/service.c b/libcroesor/service.c
index 9d5167a..dcd8f90 100644
--- a/libcroesor/service.c
+++ b/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)
{
diff --git a/libcroesor/service.h b/libcroesor/service.h
index bcde0b3..eea22c2 100644
--- a/libcroesor/service.h
+++ b/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);
diff --git a/libcroesor/static-vehicle.c b/libcroesor/static-vehicle.c
index 8b76eba..d250b39 100644
--- a/libcroesor/static-vehicle.c
+++ b/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);
diff --git a/libcroesor/static-vehicle.h b/libcroesor/static-vehicle.h
index b87ca44..aed9983 100644
--- a/libcroesor/static-vehicle.h
+++ b/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)
diff --git a/libcroesor/subscription-manager.c b/libcroesor/subscription-manager.c
index 1c9cccb..d9d9080 100644
--- a/libcroesor/subscription-manager.c
+++ b/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);
diff --git a/libcroesor/subscription-manager.h b/libcroesor/subscription-manager.h
index 3c0f4a0..8bfd4ea 100644
--- a/libcroesor/subscription-manager.h
+++ b/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)
diff --git a/libcroesor/vehicle-manager.c b/libcroesor/vehicle-manager.c
index 3f00d6b..b214b2f 100644
--- a/libcroesor/vehicle-manager.c
+++ b/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);
diff --git a/libcroesor/vehicle-manager.h b/libcroesor/vehicle-manager.h
index b196798..3f45467 100644
--- a/libcroesor/vehicle-manager.h
+++ b/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)
diff --git a/libcroesor/vehicle-service.c b/libcroesor/vehicle-service.c
index c7deeee..fe90966 100644
--- a/libcroesor/vehicle-service.c
+++ b/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);
diff --git a/libcroesor/vehicle-service.h b/libcroesor/vehicle-service.h
index 273696c..b512058 100644
--- a/libcroesor/vehicle-service.h
+++ b/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)
diff --git a/libcroesor/version.h.in b/libcroesor/version.h.in
index e04f5e7..28b972b 100644
--- a/libcroesor/version.h.in
+++ b/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
--
GitLab