sssd/0002-sbus-improve-documentation-of-SBUS_INTERFACE.patch

From e185b039468ec27bbc905c61c57dffc5496af521 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Pavel=20B=C5=99ezina?= <pbrezina@redhat.com>
Date: Tue, 5 Feb 2019 10:36:13 +0100
Subject: [PATCH 2/3] sbus: improve documentation of SBUS_INTERFACE

Reviewed-by: Alexey Tikhonov <atikhono@redhat.com>
---
 src/sbus/sbus_interface.h | 195 +++++++++++++++++++++++++++-----------
 1 file changed, 138 insertions(+), 57 deletions(-)

diff --git a/src/sbus/sbus_interface.h b/src/sbus/sbus_interface.h
index 45ab4b5ad..2312fde68 100644
--- a/src/sbus/sbus_interface.h
+++ b/src/sbus/sbus_interface.h
@@ -49,35 +49,47 @@ struct sbus_node;
  *
  * @see SBUS_SYNC, SBUS_ASYNC, SBUS_NO_METHODS, SBUS_WITHOUT_METHODS
  *
+ * The following examples demonstrate the intended usage of this macro.
+ * Do not use it in any other way.
+ *
  * @example Interface with two methods, one with synchronous handler,
  * one with asynchronous handler.
  *
- *     struct sbus_interface iface = {
- *         .name = SBUS_IFACE_ORG_FREEDESKTOP_SSSD,
- *          SBUS_METHODS(
- *              SBUS_SYNC (METHOD, org_freedekstop_sssd, UpdateMembers,
- *                         update_members_sync, pvt_data),
- *              SBUS_ASYNC(METHOD, org_freedekstop_sssd, UpdateMembersAsync,
- *                         update_members_send, update_members_recv,
- *                         pvt_data)
- *          )
- *     };
+ *     SBUS_INTERFACE(
+ *         iface_variable,
+ *         org_freedesktop_sssd,
+ *         SBUS_METHODS(
+ *             SBUS_SYNC (METHOD, org_freedekstop_sssd, UpdateMembers,
+ *                       update_members_sync, pvt_data),
+ *             SBUS_ASYNC(METHOD, org_freedekstop_sssd, UpdateMembersAsync,
+ *                        update_members_send, update_members_recv,
+ *                        pvt_data)
+ *         ),
+ *         @signals,
+ *         @properties
+ *     );
  *
  * @example Interface with no methods.
  *
- *     struct sbus_interface empty_iface = {
- *         .name = SBUS_IFACE_ORG_FREEDESKTOP_SSSD,
- *          SBUS_METHODS(
- *              SBUS_NO_METHODS
- *          )
- *     };
+ *     SBUS_INTERFACE(
+ *         iface_variable,
+ *         org_freedesktop_sssd,
+ *         SBUS_METHODS(
+ *             SBUS_NO_METHODS
+ *         ),
+ *         @signals,
+ *         @properties
+ *     );
  *
  *     or
  *
- *     struct sbus_interface empty_iface = {
- *         .name = SBUS_IFACE_ORG_FREEDESKTOP_SSSD,
- *          SBUS_WITHOUT_METHODS
- *     };
+ *     SBUS_INTERFACE(
+ *         iface_variable,
+ *         org_freedesktop_sssd,
+ *         SBUS_WITHOUT_METHODS,
+ *         @signals,
+ *         @properties
+ *     );
  */
 #define SBUS_METHODS(...)                                                     \
     {                                                                         \
@@ -91,30 +103,42 @@ struct sbus_node;
  *
  * @see SBUS_EMIT, SBUS_NO_SIGNALS, SBUS_WITHOUT_SIGNALS
  *
+ * The following examples demonstrate the intended usage of this macro.
+ * Do not use it in any other way.
+ *
  * @example Interface that can emit a PropertyChanged signal.
  *
- *     struct sbus_interface iface = {
- *         .name = SBUS_IFACE_ORG_FREEDESKTOP_SSSD,
- *          SBUS_SIGNALS(
- *              SBUS_EMIT(org_freedekstop_sssd, PropertyChanged)
- *          )
- *     };
+ *     SBUS_INTERFACE(
+ *         iface_variable,
+ *         org_freedesktop_sssd,
+ *         @methods,
+ *         SBUS_SIGNALS(
+ *             SBUS_EMIT(org_freedekstop_sssd, PropertyChanged)
+ *         ),
+ *         @properties
+ *     );
  *
  * @example Interface with no signals.
  *
- *     struct sbus_interface empty_iface = {
- *         .name = SBUS_IFACE_ORG_FREEDESKTOP_SSSD,
- *          SBUS_SIGNALS(
- *              SBUS_NO_SIGNALS
- *          )
- *     };
+ *     SBUS_INTERFACE(
+ *         iface_variable,
+ *         org_freedesktop_sssd,
+ *         @methods,
+ *         SBUS_SIGNALS(
+ *             SBUS_NO_SIGNALS
+ *         ),
+ *         @properties
+ *     );
  *
  *     or
  *
- *     struct sbus_interface empty_iface = {
- *         .name = SBUS_IFACE_ORG_FREEDESKTOP_SSSD,
- *          SBUS_WITHOUT_SIGNALS
- *     };
+ *     SBUS_INTERFACE(
+ *         iface_variable,
+ *         org_freedesktop_sssd,
+ *         @methods,
+ *         SBUS_WITHOUT_SIGNALS,
+ *         @properties
+ *     );
  */
 #define SBUS_SIGNALS(...)                                                     \
     {                                                                         \
@@ -128,35 +152,47 @@ struct sbus_node;
  *
  * @see SBUS_SYNC, SBUS_ASYNC, SBUS_NO_PROPERTIES, SBUS_WITHOUT_PROPERTIES
  *
+ * The following examples demonstrate the intended usage of this macro.
+ * Do not use it in any other way.
+ *
  * @example Interface with one property with asynchronous getter and
  * synchronous setter.
  *
- *     struct sbus_interface iface = {
- *         .name = SBUS_IFACE_ORG_FREEDESKTOP_SSSD,
- *          SBUS_PROPERTIES(
- *              SBUS_SYNC (GETTER, org_freedekstop_sssd, domain_name,
- *                         set_domain_name, pvt_data),
- *              SBUS_ASYNC(GETTER, org_freedekstop_sssd, domain_name,
- *                         get_domain_name_send, get_domain_name_recv,
- *                         pvt_data)
- *          )
- *     };
+ *     SBUS_INTERFACE(
+ *         iface_variable,
+ *         org_freedesktop_sssd,
+ *         @methods,
+ *         @signals,
+ *         SBUS_PROPERTIES(
+ *             SBUS_SYNC (GETTER, org_freedekstop_sssd, domain_name,
+ *                        set_domain_name, pvt_data),
+ *             SBUS_ASYNC(GETTER, org_freedekstop_sssd, domain_name,
+ *                        get_domain_name_send, get_domain_name_recv,
+ *                        pvt_data)
+ *         )
+ *     );
  *
  * @example Interface with no properties.
  *
- *     struct sbus_interface empty_iface = {
- *         .name = SBUS_IFACE_ORG_FREEDESKTOP_SSSD,
- *          SBUS_PROPERTIES(
- *              SBUS_NO_PROPERTIES
- *          )
- *     };
+ *     SBUS_INTERFACE(
+ *         iface_variable,
+ *         org_freedesktop_sssd,
+ *         @methods,
+ *         @signals,
+ *         SBUS_PROPERTIES(
+ *             SBUS_NO_PROPERTIES
+ *         )
+ *     );
  *
  *     or
  *
- *     struct sbus_interface empty_iface = {
- *         .name = SBUS_IFACE_ORG_FREEDESKTOP_SSSD,
- *          SBUS_WITHOUT_PROPERTIES
- *     };
+ *     SBUS_INTERFACE(
+ *         iface_variable,
+ *         org_freedesktop_sssd,
+ *         @methods,
+ *         @signals,
+ *         SBUS_WITHOUT_PROPERTIES
+ *     );
  */
 #define SBUS_PROPERTIES(...)                                                  \
     {                                                                         \
@@ -239,8 +275,53 @@ struct sbus_node;
  * @param signals      Signals on the interface.
  * @param properties   Properties on the interface.
  *
+ * Please note that the following macro introduced to the scope these variables:
+ *   - __varname_m
+ *   - __varname_s
+ *   - __varname_p
+ *
+ * These variables are intended for internal purpose only and should not be
+ * used outside this macro. They are allocated on stack and will be destroyed
+ * with it.
+ *
+ * Additionally, it creates 'struct sbus_interface varname'. This variable
+ * holds the information about the interfaces you created. The structure and
+ * all its data are allocated on stack and will be destroyed with it.
+ *
+ * The only intended usage of this variable is to assign it to an sbus path
+ * and then register this path inside the same function where the interface
+ * is defined. It should not be used in any other way.
+ *
+ * The following example demonstrates the intended usage of this macro.
+ * Do not use it in any other way.
+ *
  * @example
- *     SBUS_INTERFACE(org_freedesktop_sssd, @methods, @signals, @properties)
+ *     SBUS_INTERFACE(
+ *         iface_bus,
+ *         org_freedesktop_DBus,
+ *         SBUS_METHODS(
+ *             SBUS_SYNC(METHOD, org_freedesktop_DBus, Hello, sbus_server_bus_hello, server),
+ *             SBUS_SYNC(METHOD, org_freedesktop_DBus, RequestName, sbus_server_bus_request_name, server),
+ *         ),
+ *         SBUS_SIGNALS(
+ *             SBUS_EMITS(org_freedesktop_DBus, NameOwnerChanged),
+ *             SBUS_EMITS(org_freedesktop_DBus, NameAcquired),
+ *             SBUS_EMITS(org_freedesktop_DBus, NameLost)
+ *         ),
+ *         SBUS_WITHOUT_PROPERTIES
+ *     );
+ *
+ *     struct sbus_path paths[] = {
+ *          {"/org/freedesktop/dbus", &iface_bus},
+ *          {NULL, NULL}
+ *     };
+ *
+ *     ret = sbus_router_add_path_map(server->router, paths);
+ *     if (ret != EOK) {
+ *         DEBUG(SSSDBG_CRIT_FAILURE, "Unable to add paths [%d]: %s\n",
+ *               ret, sss_strerror(ret));
+ *         return ret;
+ *     }
  *
  * @see SBUS_METHODS, SBUS_SIGNALS, SBUS_PROPERTIES to create those arguments.
  */
-- 
2.20.1