Changeset 14548b9 in mod_gnutls for src/gnutls_cache.h

Timestamp:

Dec 5, 2016, 4:02:30 PM (4 years ago)

Author:

Thomas Klute <thomas2.klute@…>

Branches:

debian/master, debian/stretch-backports, master, proxy-ticket, upstream

Children:

104e881

Parents:

d4d066f

git-author:

Thomas Klute <thomas2.klute@…> (12/05/16 16:01:23)

git-committer:

Thomas Klute <thomas2.klute@…> (12/05/16 16:02:30)

Message:

Update comments in gnutls_cache.(c|h) to work with Doxygen

File:

• src/gnutls_cache.h (modified) (4 diffs)

src/gnutls_cache.h

@@ -1 @@
-/**
+/*
  *  Copyright 2004-2005 Paul Querna
  *  Copyright 2014 Nikos Mavrogiannopoulos
@@ -15 +15 @@
  *  See the License for the specific language governing permissions and
  *  limitations under the License.
+ */
+
+/**
+ * @file
  *
+ * Generic object cache for mod_gnutls
  */
 
@@ -24 +29 @@
 #include <httpd.h>
 
+/** Name of the mod_gnutls cache access mutex, for use with Apache's
+ * `Mutex` directive */
 #define MGS_CACHE_MUTEX_NAME "gnutls-cache"
 
 /**
- * Init the Cache after Configuration is done
+ * Initialize the internal cache configuration structure. This
+ * function is called after the configuration file(s) have been
+ * parsed.
  */
 int mgs_cache_post_config(apr_pool_t *p, server_rec *s, mgs_srvconf_rec *sc);
 
 /**
- * Init the Cache inside each Process
+ * (Re-)Initialize the cache in a child process after forking
  */
 int mgs_cache_child_init(apr_pool_t *p, server_rec *s, mgs_srvconf_rec *sc);
 
 /**
- * Setup the Session Caching
+ * Setup caching for the given TLS session
+ *
+ * @param ctxt mod_gnutls session context
+ * @return 0
  */
 int mgs_cache_session_init(mgs_handle_t *ctxt);
@@ -44 +56 @@
 
 /**
- * Convert a time_t into a null terminated string in a format
- * compatible with OpenSSL's ASN1_TIME_print()
+ * Convert a `time_t` into a null terminated string in a format
+ * compatible with OpenSSL's `ASN1_TIME_print()`
  *
  * @param t time_t time
  * @param str Location to store the time string
- * @param strsize The maximum length that can be stored in str
+ * @param strsize The maximum length that can be stored in `str`
+ * @return `str`
  */
 char *mgs_time2sz(time_t t, char *str, int strsize);
 
-/*
- * Generic object cache functions, used for OCSP caching
+/**
+ * Generic store function for the mod_gnutls object cache
+ *
+ * @param s server associated with the cache entry
+ * @param key key for the cache entry
+ * @param data data to be cached
+ * @param expiry expiration time
+ * @return -1 on error, 0 on success
  */
 typedef int (*cache_store_func)(server_rec *s, gnutls_datum_t key,
                                 gnutls_datum_t data, apr_time_t expiry);
+/**
+ * Generic fetch function for the mod_gnutls object cache
+ *
+ * @param ctxt mod_gnutls session context for the request
+ * @param key key for the cache entry to be fetched
+ * @return the requested cache entry, or `{NULL, 0}`
+ */
 typedef gnutls_datum_t (*cache_fetch_func)(mgs_handle_t *ctxt,
                                            gnutls_datum_t key);
+/**
+ * Internal cache configuration structure
+ */
 struct mgs_cache {
+    /** Store function for this cache */
     cache_store_func store;
+    /** Fetch function for this cache */
     cache_fetch_func fetch;
-    /* Mutex for cache access (used only if the cache type is not
+    /** Mutex for cache access (used only if the cache type is not
      * thread-safe) */
     apr_global_mutex_t *mutex;