Add some more FEC source code documentation.

[paraslash.git] / vss.c

diff --git a/vss.c b/vss.c
index 330bba6ab65c397b19bc1a25d9310bd15bcec70e..f1f9616768d21fdc2b682dabd5c8872b54eee2aa 100644 (file)
--- 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;
 };
 
@@ -296,7 +340,7 @@ err:
 /**
  * Remove one entry from the list of active fec clients.
  *
- * \param result The client to be removed.
+ * \param fc The client to be removed.
  */
 void vss_del_fec_client(struct fec_client *fc)
 {
@@ -335,21 +379,16 @@ static void compute_slice_timeout(struct timeval *timeout)
        assert(vss_playing());
        list_for_each_entry(fc, &fec_client_list, node) {
                struct timeval diff;
-               int ret = next_slice_is_due(fc, &diff);
 
-               // PARA_NOTICE_LOG("diff: %lu, ret: %d\n", tv2ms(&diff), ret);
-               if (ret) {
+               if (next_slice_is_due(fc, &diff)) {
                        timeout->tv_sec = 0;
                        timeout->tv_usec = 0;
-                       goto out;
+                       return;
                }
                /* timeout = min(timeout, diff) */
                if (tv_diff(&diff, timeout, NULL) < 0)
                        *timeout = diff;
        }
-out:
-       return;
-       PARA_NOTICE_LOG("slice timeout: %lu:%lu\n", (long unsigned)timeout->tv_sec, (long unsigned)timeout->tv_usec);
 }
 
 /**