a bit more doxygen

diff --git a/lib/addr.c b/lib/addr.c
index 153130bf65cf31634d8187ee4e3b917f0d63731e..07876633950dd870d69f458dc7d67de25ea1c857 100644 (file)
--- a/lib/addr.c
+++ b/lib/addr.c
@@ -88,6 +88,10 @@ struct addrinfo *get_address(const struct stringlist *a,
   return res;
 }
 
+/** @brief Comparison function for address information
+ *
+ * Suitable for qsort().
+ */
 int addrinfocmp(const struct addrinfo *a,
                const struct addrinfo *b) {
   const struct sockaddr_in *ina, *inb;

diff --git a/lib/asprintf.c b/lib/asprintf.c
index f590c0ad3c15391087a56b05a4fa9af928759dbd..d4678745701b1589c829b2d0a7a706d56738d38a 100644 (file)
--- a/lib/asprintf.c
+++ b/lib/asprintf.c
@@ -33,6 +33,12 @@
 #include "vector.h"
 #include "log.h"
 
+/** @brief vasprintf() workalike without encoding errors
+ *
+ * This acts like vasprintf() except that it does not throw an error
+ * if you use a string outside the current locale's encoding rules,
+ * and it uses the memory allocation calls from @ref mem.h.
+ */
 int byte_vasprintf(char **ptrp,
                   const char *fmt,
                   va_list ap) {
@@ -47,6 +53,12 @@ int byte_vasprintf(char **ptrp,
   return n;
 }
 
+/** @brief asprintf() workalike without encoding errors
+ *
+ * This acts like asprintf() except that it does not throw an error
+ * if you use a string outside the current locale's encoding rules,
+ * and it uses the memory allocation calls from @ref mem.h.
+ */
 int byte_asprintf(char **ptrp,
                  const char *fmt,
                  ...) {
@@ -59,6 +71,13 @@ int byte_asprintf(char **ptrp,
   return n;
 }
 
+/** @brief asprintf() workalike without encoding errors
+ *
+ * This acts like asprintf() except that it does not throw an error if
+ * you use a string outside the current locale's encoding rules; it
+ * uses the memory allocation calls from @ref mem.h; and it terminates
+ * the program on error.
+ */
 int byte_xasprintf(char **ptrp,
                   const char *fmt,
                   ...) {
@@ -71,6 +90,13 @@ int byte_xasprintf(char **ptrp,
   return n;
 }
 
+/** @brief vasprintf() workalike without encoding errors
+ *
+ * This acts like vasprintf() except that it does not throw an error
+ * if you use a string outside the current locale's encoding rules; it
+ * uses the memory allocation calls from @ref mem.h; and it terminates
+ * the program on error.
+ */
 int byte_xvasprintf(char **ptrp,
                    const char *fmt,
                    va_list ap) {

diff --git a/lib/authhash.c b/lib/authhash.c
index a1012ba0e9ba570ee8c905dc4c2cf823d917b13a..5c66c012c890eeaf1cd742290aa68865bb4adbab 100644 (file)
--- a/lib/authhash.c
+++ b/lib/authhash.c
@@ -30,9 +30,19 @@
 #include "authhash.h"
 
 #ifndef AUTHHASH
+/** @brief Which hash function to use */
 # define AUTHHASH GCRY_MD_SHA1
 #endif
 
+/** @brief Perform the authorization hash function
+ * @param challenge Pointer to challange
+ * @param nchallenge Size of challenge
+ * @param password Password
+ *
+ * Computes H(challenge|password) and returns it as a newly allocated hex
+ * string.  Currently the hash function is SHA-1, but this may be changed in
+ * future versions; see @ref AUTHHASH.
+ */
 const char *authhash(const void *challenge, size_t nchallenge,
                     const char *password) {
   gcrypt_hash_handle h;

diff --git a/lib/basen.c b/lib/basen.c
index 69ab273d21d4f591cb22dfabc678d3aeec690b89..362ab58311a0b1ab9cc555abc7ffb40635f5e447 100644 (file)
--- a/lib/basen.c
+++ b/lib/basen.c
@@ -25,7 +25,11 @@
 
 #include "basen.h"
 
-/* test whether v is 0 */
+/** @brief Test whether v is 0
+ * @param v Pointer to bigendian bignum
+ * @param nwords Length of bignum
+ * @return !v
+ */
 static int zero(const unsigned long *v, int nwords) {
   int n;
 
@@ -34,7 +38,14 @@ static int zero(const unsigned long *v, int nwords) {
   return n == nwords;
 }
 
-/* divide v by m returning the remainder */
+/** @brief Divide v by m returning the remainder.
+ * @param v Pointer to bigendian bignum
+ * @param nwords Length of bignum
+ * @param m Divisor (must not be 0)
+ * @return Remainder
+ *
+ * The quotient is stored in @p v.
+ */
 static unsigned divide(unsigned long *v, int nwords, unsigned long m) {
   unsigned long r = 0, a, b;
   int n;
@@ -54,6 +65,17 @@ static unsigned divide(unsigned long *v, int nwords, unsigned long m) {
   return r;
 }
 
+/** @brief Convert v to a chosen base
+ * @param v Pointer to bigendian bignum
+ * @param nwords Length of bignum
+ * @param buffer Output buffer
+ * @param bufsize Size of output buffer
+ * @param base Number base (2..62)
+ * @return 0 on success, -1 if the buffer is too small
+ *
+ * Converts @p v to a string in the given base using decimal digits, lower case
+ * letter sand upper case letters as digits.
+ */
 int basen(unsigned long *v,
          int nwords,
          char buffer[],

diff --git a/lib/cache.c b/lib/cache.c
index c6624e89d0f4b6ba04a0f2b39670bd64601de4a2..368ec37b3b02cf548631120820dcba6e5eff05c7 100644 (file)
--- a/lib/cache.c
+++ b/lib/cache.c
@@ -28,18 +28,31 @@
 #include "log.h"
 #include "cache.h"
 
+/** @brief The global cache */
 static hash *h;
 
+/** @brief One cache entry */
 struct cache_entry {
+  /** @brief What type of object this is */
   const struct cache_type *type;
+
+  /** @brief Pointer to object value */
   const void *value;
+
+  /** @brief Time that object was inserted into cache */
   time_t birth;
 };
 
+/** @brief Return true if object @p c has expired */
 static int expired(const struct cache_entry *c, time_t now) {
   return now - c->birth > c->type->lifetime;
 }
 
+/** @brief Insert an object into the cache
+ * @param type Pointer to object type
+ * @param key Unique key
+ * @param value Pointer to value
+ */
 void cache_put(const struct cache_type *type,
                const char *key, const void *value) {
   struct cache_entry *c;
@@ -53,6 +66,11 @@ void cache_put(const struct cache_type *type,
   hash_add(h, key, c,  HASH_INSERT_OR_REPLACE);
 }
 
+/** @brief Look up an object in the cache
+ * @param type Pointer to object type
+ * @param key Unique key
+ * @return Pointer to object value or NULL if not found
+ */
 const void *cache_get(const struct cache_type *type, const char *key) {
   const struct cache_entry *c;
   
@@ -74,6 +92,9 @@ static int expiry_callback(const char *key, void *value, void *u) {
   return 0;
 }
 
+/** @brief Expire the cache
+ *
+ * Called from time to time to expire cache entries. */
 void cache_expire(void) {
   time_t now;
 
@@ -92,11 +113,20 @@ static int clean_callback(const char *key, void *value, void *u) {
   return 0;
 }
 
+/** @brief Clean the cache
+ * @param type Pointer to type to clean
+ *
+ * Removes all entries of type @p type from the cache.
+ */
 void cache_clean(const struct cache_type *type) {
   if(h)
     hash_foreach(h, clean_callback, (void *)type);
 }
 
+/** @brief Report cache size
+ *
+ * Returns the number of objects in the cache
+ */
 size_t cache_count(void) {
   return h ? hash_count(h) : 0;
 }