From 36bc7580a5ddee8f6e46bccfea7519291f372f0f Mon Sep 17 00:00:00 2001
From: Andre Noll <maan@systemlinux.org>
Date: Sun, 1 Mar 2009 13:24:31 +0100
Subject: [PATCH] Add some more FEC source code documentation.

---
 fecdec_filter.c | 20 +++++++++++++++++---
 vss.c           | 44 ++++++++++++++++++++++++++++++++++++++++++++
 vss.h           |  6 ++++++
 3 files changed, 67 insertions(+), 3 deletions(-)

diff --git a/fecdec_filter.c b/fecdec_filter.c
index a17ddf7c..6bb827c8 100644
--- a/fecdec_filter.c
+++ b/fecdec_filter.c
@@ -18,21 +18,35 @@
 #include "fec.h"
 #include "fd.h"
 
+/**
+ * How many FEC groups to store in memory.
+ *
+ * Packet reordering requires to keep more than one FEC group in memory because
+ * slices belonging to the next FEC group may arrive before the current FEC group
+ * is complete.
+ */
 #define NUM_FEC_GROUPS 3
+
 #define INPUT_BUFFER_SIZE 16384
 
-/** size of the output buffer */
+/** Size of the output buffer of the fecdec filter. */
 #define FECDEC_OUTBUF_SIZE 81920
 
+/** Data read from the header of a slice. */
 struct fec_header {
+	/** Total number of slices in this group. */
 	uint8_t slices_per_group;
+	/** Number of slices needed to start decoding. */
 	uint8_t data_slices_per_group;
+	/** Size of the ogg vorbis header (zero for mp3, aac). */
 	uint32_t audio_header_size;
-
+	/** Number of the FEC group this slice belongs to. */
 	uint32_t group_num;
+	/** Size of the data in this FEC group. */
 	uint32_t group_bytes;
-
+	/** Number of this slice in the group. */
 	uint8_t slice_num;
+	/** Used data bytes of this slice. */
 	uint16_t slice_bytes;
 };
 
diff --git a/vss.c b/vss.c
index eef3a632..f1f96167 100644
--- a/vss.c
+++ b/vss.c
@@ -89,35 +89,79 @@ struct vss_task {
 	size_t header_len;
 };
 
+/**
+ * The list of currently connected fec clients.
+ *
+ * Senders may use \ref vss_add_fec_client() to add entries to the list.
+ */
 static struct list_head fec_client_list;
 
+/**
+ * Describes one slice of a FEC group.
+ *
+ * FEC slices directly correspond to the data packages sent by the paraslash
+ * senders that use FEC. Each slice is identified by its group number and its
+ * number within the group. All slices have the same size, but the last slice
+ * of the group may not be filled entirely.
+ */
 struct fec_slice {
+	/** The slice number within the FEC group. */
 	uint8_t num;
+	/** The number of used bytes in this slice. */
 	uint16_t bytes;
 };
 
+/**
+ * Data associated with one FEC group.
+ *
+ * A FEC group consists of a fixed number of slices and this number is given by
+ * the \a slices_per_group parameter of struct \ref fec_client_parms. Each FEC
+ * group contains a number of chunks of the current audio file.
+ */
 struct fec_group {
+	/** The number of the FEC group. */
 	uint32_t num;
+	/** Number of bytes in this group. */
 	uint32_t bytes;
+	/** The first chunk of the current audio file belonging to the group. */
 	uint32_t first_chunk;
+	/** The number of chunks contained in this group. */
 	uint32_t num_chunks;
+	/** The time needed to play all chunks of the group. */
 	struct timeval duration;
+	/** When the first chunk was sent. */
 	struct timeval start;
+	/** \a The group duration divided by \a slices_per_group. */
 	struct timeval slice_duration;
 };
 
+/**
+ * Describes one connected FEC client.
+ */
 struct fec_client {
+	/** Parameters requested by the client. */
 	struct fec_client_parms *fcp;
+	/** Used by the core FEC code. */
 	struct fec_parms *parms;
+	/** The position of this client in \a \ref fec_client_list. */
 	struct list_head node;
+	/** When the first slice for this client was sent. */
 	struct timeval stream_start;
+	/** The first chunk sent to this FEC client. */
 	int first_stream_chunk;
+	/** Describes the current group. */
 	struct fec_group group;
+	/** Describes the current slice. */
 	struct fec_slice slice;
+	/** The data to be FEC-encoded (point to a region within the mapped audio file). */
 	const unsigned char **src_data;
+	/** Used for the last source pointer of the last group. */
 	unsigned char *extra_src_buf;
+	/** The size of the buffer for the extra source pointer. */
 	size_t extra_src_buf_size;
+	/** Contains FEC-encoded data. */
 	unsigned char *enc_buf;
+	/** Size of \a enc_buf. */
 	size_t enc_buf_size;
 };
 
diff --git a/vss.h b/vss.h
index efabdf36..abe7a570 100644
--- a/vss.h
+++ b/vss.h
@@ -38,11 +38,17 @@ const char *supported_audio_formats(void);
  */
 struct fec_client;
 
+/** FEC parameters requested by FEC clients. */
 struct fec_client_parms {
+	/** Number of data slices plus redundant slices. */
 	uint8_t slices_per_group;
+	/** Number of slices minus number of redundant slices. */
 	uint8_t data_slices_per_group;
+	/** Maximal number of bytes per slice. */
 	uint16_t max_slice_bytes;
+	/** Called by vss.c when the next slice should be sent. */
 	int (*send)(char *buf, size_t num_bytes, void *private_data);
+	/** Passed verbatim to \a send(). */
 	void *private_data;
 };
 
-- 
2.39.5