GUAC-1389: Document client process map manipulation functions.

src/guacd/proc-map.c

@@ -32,7 +32,13 @@
 #include <string.h>
 
 /**
- * Returns a hash code based on the connection ID of the given client.
+ * Returns a hash code based on the given connection ID.
+ *
+ * @param str
+ *     The string containing the connection ID.
+ *
+ * @return
+ *     A reasonably well-distributed hash code for the given string.
  */
 static unsigned int __guacd_client_hash(const char* str) {
 
@@ -48,10 +54,22 @@ static unsigned int __guacd_client_hash(const char* str) {
 }
 
 /**
- * Locates the bucket corresponding to the hash code indicated by the give id.
+ * Locates the bucket corresponding to the hash code indicated by the given id,
- * Each bucket is an instance of guac_common_list.
+ * where the hash code is dictated by __guacd_client_hash().  Each bucket is an
+ * instance of guac_common_list.
+ *
+ * @param map
+ *     The map to retrieve the hash bucket from.
+ *
+ * @param id
+ *     The ID whose hash code determines the bucket being retrieved.
+ *
+ * @return
+ *     The bucket corresponding to the hash code for the given ID, represented
+ *     by a guac_common_list.
  */
-static guac_common_list* __guacd_proc_find_bucket(guacd_proc_map* map, const char* id) {
+static guac_common_list* __guacd_proc_find_bucket(guacd_proc_map* map,
+        const char* id) {
 
     const int index = __guacd_client_hash(id) % GUACD_PROC_MAP_BUCKETS;
     return map->__buckets[index];
@@ -59,11 +77,24 @@ static guac_common_list* __guacd_proc_find_bucket(guacd_proc_map* map, const cha
 }
 
 /**
- * Given a list of guacd_proc instances, returns the
+ * Given a bucket of guacd_proc instances, returns the guacd_proc having the
- * guacd_proc having the guac_client with the given ID, or NULL if no
+ * guac_client with the given ID, or NULL if no such client is stored.
- * such client is stored.
+ *
+ * @param bucket
+ *     The bucket of guacd_proc instances to search, represented as a
+ *     guac_common_list.
+ *
+ * @param id
+ *     The ID of the guac_client whose corresponding guacd_proc instance should
+ *     be located within the bucket.
+ *
+ * @return
+ *     The guac_common_list_element containing the guacd_proc instance
+ *     corresponding to the guac_client having the given ID, or NULL of no such
+ *     element exists.
  */
-static guac_common_list_element* __guacd_proc_find(guac_common_list* bucket, const char* id) {
+static guac_common_list_element* __guacd_proc_find(guac_common_list* bucket,
+        const char* id) {
 
     guac_common_list_element* current = bucket->head;
 

src/guacd/proc-map.h

@@ -50,27 +50,63 @@ typedef struct guacd_proc_map {
 } guacd_proc_map;
 
 /**
- * Allocates a new client process map, which persists for the life of guacd.
+ * Allocates a new client process map. There is intended to be exactly one
+ * process map instance, which persists for the life of guacd.
+ *
+ * @return
+ *     A newly-allocated client process map.
  */
 guacd_proc_map* guacd_proc_map_alloc();
 
 /**
- * Adds the given process to the client process map. On success, zero is returned.  If
+ * Adds the given process to the client process map. On success, zero is
- * adding the client fails (due to lack of space, or duplicate ID), a non-zero
+ * returned. If adding the client fails (due to lack of space, or duplicate
- * value is returned instead. The client process is stored by the connection ID
+ * ID), a non-zero value is returned instead. The client process is stored by
- * of the underlying guac_client.
+ * the connection ID of the underlying guac_client.
+ *
+ * @param map
+ *     The map in which the given client process should be stored.
+ *
+ * @param proc
+ *     The client process to store in the given map.
+ *
+ * @return
+ *     Zero if the process was successfully stored in the map, or non-zero if
+ *     storing the process fails for any reason.
  */
 int guacd_proc_map_add(guacd_proc_map* map, guacd_proc* proc);
 
 /**
  * Retrieves the client process having the client with the given ID, or NULL if
  * no such process is stored.
+ *
+ * @param map
+ *     The map from which to retrieve the process associated with the client
+ *     having the given ID.
+ *
+ * @param id
+ *     The ID of the client whose process should be retrieved.
+ *
+ * @return
+ *     The process associated with the client having the given ID, or NULL if
+ *     no such process exists.
  */
 guacd_proc* guacd_proc_map_retrieve(guacd_proc_map* map, const char* id);
 
 /**
  * Removes the client process having the client with the given ID, returning
  * the corresponding process. If no such process exists, NULL is returned.
+ *
+ * @param map
+ *     The map from which to remove the process associated with the client
+ *     having the given ID.
+ *
+ * @param id
+ *     The ID of the client whose process should be removed.
+ *
+ * @return
+ *     The process associated with the client having the given ID which has now
+ *     been removed from the given map, or NULL if no such process exists.
  */
 guacd_proc* guacd_proc_map_remove(guacd_proc_map* map, const char* id);