From 05e00b5d3070f35b230e0f0beb2b6a93a97b38c5 Mon Sep 17 00:00:00 2001
From: Andre Noll <maan@systemlinux.org>
Date: Sun, 20 Dec 2009 12:37:21 +0100
Subject: [PATCH] Add some missing FEC documentation.

---
 fec.c           | 37 ++++++++++++++++++++++++++++---------
 fec.h           |  4 +++-
 fecdec_filter.c | 11 +++++++++++
 3 files changed, 42 insertions(+), 10 deletions(-)

diff --git a/fec.c b/fec.c
index d097b77d..dc6e7520 100644
--- a/fec.c
+++ b/fec.c
@@ -41,20 +41,36 @@
 #include "string.h"
 #include "fec.h"
 
-#define GF_BITS  8 /* code over GF(256) */
+/** Code over GF(256). */
+#define GF_BITS  8
+/** The largest number in GF(256) */
 #define	GF_SIZE ((1 << GF_BITS) - 1)
 
 /*
  * To speed up computations, we have tables for logarithm, exponent and inverse
- * of a number. We use a table for multiplication as well (it takes 64K, no big
- * deal even on a PDA, especially because it can be pre-initialized an put into
- * a ROM!). The macro gf_mul(x,y) takes care of multiplications.
+ * of a number.
+ */
+
+/** Index->poly form conversion table. */
+static unsigned char gf_exp[2 * GF_SIZE];
+
+/** Poly->index form conversion table. */
+static int gf_log[GF_SIZE + 1];
+
+/** Inverse of a field element. */
+static unsigned char inverse[GF_SIZE + 1];
+
+/**
+ * The multiplication table.
+ *
+ * We use a table for multiplication as well. It takes 64K, no big deal even on
+ * a PDA, especially because it can be pre-initialized and put into a ROM.
+ *
+ * \sa \ref gf_mul.
  */
-static unsigned char gf_exp[2 * GF_SIZE]; /* index->poly form conversion table */
-static int gf_log[GF_SIZE + 1];	/* Poly->index form conversion table    */
-static unsigned char inverse[GF_SIZE + 1]; /* inverse of field elem. */
 static unsigned char gf_mul_table[GF_SIZE + 1][GF_SIZE + 1];
-/* Multiply two numbers. */
+
+/** Multiply two GF numbers. */
 #define gf_mul(x,y) gf_mul_table[x][y]
 
 /* Compute x % GF_SIZE without a slow divide. */
@@ -154,13 +170,15 @@ static void generate_gf(void)
 		inverse[i] = gf_exp[GF_SIZE - gf_log[i]];
 }
 
+/** How often the loop is unrolled. */
+#define UNROLL 16
+
 /*
  * Compute dst[] = dst[] + c * src[]
  *
  * This is used often, so better optimize it! Currently the loop is unrolled 16
  * times. The case c=0 is also optimized, whereas c=1 is not.
  */
-#define UNROLL 16
 static void addmul(unsigned char *dst1, const unsigned char const *src1,
 	unsigned char c, int sz)
 {
@@ -211,6 +229,7 @@ static void matmul(unsigned char *a, unsigned char *b, unsigned char *c,
 	}
 }
 
+/** Swap two numbers. */
 #define FEC_SWAP(a,b) {typeof(a) tmp = a; a = b; b = tmp;}
 
 /*
diff --git a/fec.h b/fec.h
index 1e28e8a4..d09b035d 100644
--- a/fec.h
+++ b/fec.h
@@ -33,8 +33,10 @@
  * OF SUCH DAMAGE.
  */
 
-#define FEC_MAGIC 0xFECC0DEC
+/** Each FEC slice contains a FEC header of this size. */
 #define FEC_HEADER_SIZE 32
+/** The FEC header starts with this magic value. */
+#define FEC_MAGIC 0xFECC0DEC
 
 struct fec_parms;
 
diff --git a/fecdec_filter.c b/fecdec_filter.c
index 139a86fa..ca7c7dd3 100644
--- a/fecdec_filter.c
+++ b/fecdec_filter.c
@@ -245,10 +245,21 @@ static int add_slice(char *buf, struct fecdec_group *fg)
 	return 1;
 }
 
+/**
+ * The different states of a complete FEC group.
+ *
+ * Even if a FEC group has been received successfully, it probably can not be
+ * used right away because some streams (ogg, wma) need to receive an audio
+ * file header before decoding can start.
+ */
 enum fec_group_usability {
+	/** Drop the group (because we did not receive the header yet). */
 	FEC_GROUP_UNUSABLE,
+	/** Use all data in the group. */
 	FEC_GROUP_USABLE,
+	/** Use the group, but drop its audio file header. */
 	FEC_GROUP_USABLE_SKIP_HEADER,
+	/** Use the group, including its header. */
 	FEC_GROUP_USABLE_WITH_HEADER
 };
 
-- 
2.39.5