From 4d82d5796332e2abe77a17a6bf7e5238bcbe297e Mon Sep 17 00:00:00 2001
Message-Id: <4d82d5796332e2abe77a17a6bf7e5238bcbe297e.1715272816.git.mdw@distorted.org.uk>
From: Mark Wooding <mdw@chiark.greenend.org.uk>
Date: Sun, 26 Oct 2008 12:17:38 +0000
Subject: [PATCH] A bit more doxygen
Organization: Straylight/Edgeware

From: Richard Kettlewell <rjk@greenend.org.uk>

---
 lib/alsabg.c   | 10 ++++++++++
 lib/alsabg.h   |  1 +
 lib/arcfour.c  | 16 ++++++++++++++++
 lib/arcfour.h  |  1 +
 lib/authhash.c |  4 ++++
 5 files changed, 32 insertions(+)

diff --git a/lib/alsabg.c b/lib/alsabg.c
index 27c5c6e..56e5c6a 100644
--- a/lib/alsabg.c
+++ b/lib/alsabg.c
@@ -17,6 +17,12 @@
  */
 /** @file alsabg.c
  * @brief Background-thread interface to ALSA
+ *
+ * This wraps ALSA with an interface which calls back to the client from a
+ * thread.  It's not intended for completely general use, just what DisOrder
+ * needs.
+ *
+ * Only builds on Linux systems.
  */
 
 #include "common.h"
@@ -273,6 +279,10 @@ void alsa_bg_init(const char *device,
   ep(pthread_create(&alsa_bg_play_tid, 0, alsa_bg_play, 0));
 }
 
+/** @brief Deinitialize background ALSA playback
+ *
+ * The opposite of alsa_bg_init().
+ */
 void alsa_bg_close(void) {
   void *r;
 
diff --git a/lib/alsabg.h b/lib/alsabg.h
index b378f6f..78c83dc 100644
--- a/lib/alsabg.h
+++ b/lib/alsabg.h
@@ -29,6 +29,7 @@
 /** @brief Supply audio callback
  * @param dst Where to write audio data
  * @param nsamples Number of samples to write
+ * @return Number of samples written
  *
  * This function should write up to @p *nsamples samples of data at
  * @p dst, and return the number of samples written, or -1 if some error
diff --git a/lib/arcfour.c b/lib/arcfour.c
index 7d469d8..3450562 100644
--- a/lib/arcfour.c
+++ b/lib/arcfour.c
@@ -31,6 +31,15 @@
 
 #include "arcfour.h"
 
+/** @brief Encrypt using Arcfour stream cipher
+ * @param context Context structure
+ * @param inbuf Input buffer
+ * @param outbuf Output buffer
+ * @param length Number of bytes in @p inbuf
+ *
+ * Copies from @p inbuf to @p outbuf, encrypting (or decrypting) using
+ * the stream controlled by @p context.
+ */
 void
 arcfour_stream (arcfour_context * context, const char *inbuf, char *outbuf,
 		size_t length)
@@ -56,6 +65,13 @@ arcfour_stream (arcfour_context * context, const char *inbuf, char *outbuf,
   context->idx_j = j;
 }
 
+/** @brief Initialize an @ref arcfour_context
+ * @param context Context structure
+ * @param key Key data
+ * @param keylen Length of key
+ *
+ * Initializes @p context using @p key.
+ */
 void
 arcfour_setkey (arcfour_context * context, const char *key, size_t keylen)
 {
diff --git a/lib/arcfour.h b/lib/arcfour.h
index af6e941..4993961 100644
--- a/lib/arcfour.h
+++ b/lib/arcfour.h
@@ -32,6 +32,7 @@
 
 #define ARCFOUR_SBOX_SIZE 256
 
+/** @brief Context structture for Arcfour stream cipher */
 typedef struct
 {
   char sbox[ARCFOUR_SBOX_SIZE];
diff --git a/lib/authhash.c b/lib/authhash.c
index 9d36fef..d5da9c5 100644
--- a/lib/authhash.c
+++ b/lib/authhash.c
@@ -28,7 +28,10 @@
 
 /** @brief Structure of algorithm lookup table */
 struct algorithm {
+  /** @brief DisOrder algorithm name */
   const char *name;
+
+  /** @brief gcrypt algorithm ID */
   int id;
 };
 
@@ -56,6 +59,7 @@ static const struct algorithm algorithms[] = {
  * @param nchallenge Size of challenge
  * @param password Password
  * @param algo Algorithm to use
+ * @return Hex string or NULL on error
  *
  * Computes H(challenge|password) and returns it as a newly allocated hex
  * string, or returns NULL on error.
-- 
[mdw]