From 7c15a05f6c2b5be2b78d1c277e82ee1613559c25 Mon Sep 17 00:00:00 2001
From: Nikolai Kondrashov <Nikolai.Kondrashov@redhat.com>
Date: Fri, 15 Jul 2016 13:13:52 +0300
Subject: [PATCH 01/12] Add and correct some code documentation

---
 src/responder/common/responder.h        | 23 ++++++++++++++---
 src/responder/common/responder_packet.c | 45 +++++++++++++++++++--------------
 src/responder/nss/nsssrv_cmd.c          | 32 ++++++++++++++++++++++-
 src/responder/nss/nsssrv_private.h      | 26 +++++++++++--------
 4 files changed, 92 insertions(+), 34 deletions(-)

diff --git a/src/responder/common/responder.h b/src/responder/common/responder.h
index 335b313..8d96a39 100644
--- a/src/responder/common/responder.h
+++ b/src/responder/common/responder.h
@@ -88,6 +88,7 @@ struct be_conn {
     struct sbus_connection *conn;
 };
 
+/** Responder context */
 struct resp_ctx {
     struct tevent_context *ev;
     struct tevent_fd *lfde;
@@ -123,16 +124,19 @@ struct resp_ctx {
 
     uint32_t cache_req_num;
 
-    void *pvt_ctx;
+    void *pvt_ctx;          /**< Specific responder's private context.
+                                 E.g. NSS client info, etc. for NSS
+                                 responder */
 
     bool shutting_down;
 };
 
 struct cli_creds;
 
+/** Client context */
 struct cli_ctx {
-    struct tevent_context *ev;
-    struct resp_ctx *rctx;
+    struct tevent_context *ev;          /**< The tevent context to add events to */
+    struct resp_ctx *rctx;              /**< Responder context */
     int cfd;
     struct tevent_fd *cfde;
     tevent_fd_handler_t cfd_handler;
@@ -141,7 +145,7 @@ struct cli_ctx {
 
     struct cli_creds *creds;
 
-    void *protocol_ctx;
+    void *protocol_ctx;                 /**< Protocol context */
     void *state_ctx;
 
     struct tevent_timer *idle;
@@ -327,6 +331,17 @@ void idle_handler(struct tevent_context *ev,
 
 #define GET_DOMAINS_DEFAULT_TIMEOUT 60
 
+/**
+ * Discover trusted domains and store them as sssd's subdomains.
+ *
+ * @param mem_ctx   The memory context to allocate request with.
+ * @param rctx      Responder context to work with.
+ * @param force     Ignore timeouts and do request now, if true,
+ *                  observe timeouts, if false.
+ * @param hint
+ *
+ * @return Created event, or NULL if event creation failed.
+ */
 struct tevent_req *sss_dp_get_domains_send(TALLOC_CTX *mem_ctx,
                                            struct resp_ctx *rctx,
                                            bool force,
diff --git a/src/responder/common/responder_packet.c b/src/responder/common/responder_packet.c
index 4f5e110..97f93b0 100644
--- a/src/responder/common/responder_packet.c
+++ b/src/responder/common/responder_packet.c
@@ -31,21 +31,22 @@
 #define SSSSRV_PACKET_MEM_SIZE 512
 
 struct sss_packet {
-    size_t memsize;
-
-    /* Structure of the buffer:
-    * Bytes    Content
-    * ---------------------------------
-    * 0-15     packet header
-    * 0-3      packet length (uint32_t)
-    * 4-7      command type (uint32_t)
-    * 8-11     status (uint32_t)
-    * 12-15    reserved
-    * 16+      packet body */
-    uint8_t *buffer;
-
-    /* io pointer */
-    size_t iop;
+    size_t memsize;     /**< Packet buffer size */
+
+    uint8_t *buffer;    /**< Packet buffer with the following structure:
+                         * <pre>
+                         * Bytes    Content
+                         * ---------------------------------
+                         * 0-15     packet header
+                         * 0-3      packet length (uint32_t)
+                         * 4-7      command type (uint32_t)
+                         * 8-11     status (uint32_t)
+                         * 12-15    reserved
+                         * 16+      packet body
+                         * </pre>
+                         */
+
+    size_t iop;         /**< Current I/O pointer */
 };
 
 /* Offsets to data in sss_packet's buffer */
@@ -59,11 +60,17 @@ static void sss_packet_set_cmd(struct sss_packet *packet,
                                enum sss_cli_command cmd);
 static uint32_t sss_packet_get_len(struct sss_packet *packet);
 
-/*
- * Allocate a new packet structure
+/**
+ * Allocate and initialize an empty packet.
+ *
+ * @param mem_ctx   Context to allocate the packet with.
+ * @param size      Packet body size.
+ *                  If zero, SSSSRV_PACKET_MEM_SIZE is used instead.
+ * @param rpacket   Location for the created packet pointer, cannot be NULL.
  *
- * - if size is defined use it otherwise the default packet will be
- *   SSSSRV_PACKET_MEM_SIZE bytes.
+ * @return Error code:
+ *          ENOMEM - memory allocation failed,
+ *          EOK - packet created successfully.
  */
 int sss_packet_new(TALLOC_CTX *mem_ctx, size_t size,
                    enum sss_cli_command cmd,
diff --git a/src/responder/nss/nsssrv_cmd.c b/src/responder/nss/nsssrv_cmd.c
index 573959e..edcfee4 100644
--- a/src/responder/nss/nsssrv_cmd.c
+++ b/src/responder/nss/nsssrv_cmd.c
@@ -234,6 +234,18 @@ static const char *get_homedir_override(TALLOC_CTX *mem_ctx,
                                    dom->case_preserve, homedir_ctx);
 }
 
+/**
+ * Retrieve a user's overriden shell value from an LDB message, according to
+ * global and user's domain-specific configuration.
+ *
+ * @param mem_ctx   Context to allocate returned value with.
+ * @param msg       The LDB message to retrieve user info from.
+ * @param nctx      NSS context to operate within.
+ * @param dom       Domain the user belongs to.
+ *
+ * @return User shell allocated with mem_ctx, or NULL on allocation error,
+ *         or unspecified shell.
+ */
 static const char *get_shell_override(TALLOC_CTX *mem_ctx,
                                       struct ldb_message *msg,
                                       struct nss_ctx *nctx,
@@ -400,6 +412,24 @@ done:
     return ret;
 }
 
+/**
+ * Transfer user information from LDB messages to a packet and NSS memory
+ * cache.
+ *
+ * @param packet        The packet to transfer user information to.
+ * @param dom           Domain the users belong to.
+ * @param nctx          NSS context the operation is carried within.
+ * @param filter_users  True if users present in negative cache should be
+ *                      skipped, false otherwise.
+ * @param pw_mmap_cache True if unskipped users should be stored in mmap
+ *                      cache referenced by nctx, if it's present.
+ * @param msgs          Array of LDB messages containing user information to
+ *                      be transferred.
+ * @param count         Number of LDB messages in msgs array to transfer user
+ *                      information from.
+ *
+ * @return Status code.
+ */
 static int fill_pwent(struct sss_packet *packet,
                       struct sss_domain_info *dom,
                       struct nss_ctx *nctx,
@@ -781,7 +811,7 @@ errno_t check_cache(struct nss_dom_ctx *dctx,
         return ENOENT;
     }
 
-    /* In case of local view we have to always contant DP with the original
+    /* In case of local view we have to always contact DP with the original
      * name or id. */
     get_dp_name_and_id(dctx->cmdctx, dctx->domain, req_type, opt_name, opt_id,
                        &name, &id);
diff --git a/src/responder/nss/nsssrv_private.h b/src/responder/nss/nsssrv_private.h
index 391eaaf..e686771 100644
--- a/src/responder/nss/nsssrv_private.h
+++ b/src/responder/nss/nsssrv_private.h
@@ -40,17 +40,21 @@ struct nss_state_ctx {
     int netgrent_cur;
 };
 
+/** NSS command execution context */
 struct nss_cmd_ctx {
-    struct cli_ctx *cctx;
-    enum sss_cli_command cmd;
-    char *name;
-    const char *normalized_name;
-    bool name_is_upn;
-    uint32_t id;
+    struct cli_ctx *cctx;           /**< Client context */
+    enum sss_cli_command cmd;       /**< Command being executed */
+    char *name;                     /**< Name of the entry being requested */
+    const char *normalized_name;    /**< Normalized name of the entry being requested */
+    bool name_is_upn;               /**< Names above are Kerberos UPNs */
+    uint32_t id;                    /**< ID of the entry being looked up */
     char *secid;
 
     bool immediate;
-    bool check_next;
+    bool check_next;                /**< False if only the domain pointed to
+                                         by the domain context should be
+                                         looked up, true if following linked
+                                         domains should also be looked up */
     bool enum_cached;
 
     int saved_dom_idx;
@@ -77,13 +81,15 @@ struct getent_ctx {
 };
 
 struct nss_dom_ctx {
-    struct nss_cmd_ctx *cmdctx;
-    struct sss_domain_info *domain;
+    struct nss_cmd_ctx *cmdctx;         /**< Parent command context */
+    struct sss_domain_info *domain;     /**< Domain to start lookup from */
 
     /* For a case when we are discovering subdomains */
     const char *rawname;
 
-    bool check_provider;
+    bool check_provider;                /**< True if the current domain's
+                                             cache needs refresh from the
+                                             provider, false otherwise */
 
     /* cache results */
     struct ldb_result *res;
-- 
2.8.1

