Add some missing source code documentation.
authorAndre Noll <maan@systemlinux.org>
Sun, 10 May 2009 18:41:11 +0000 (20:41 +0200)
committerAndre Noll <maan@systemlinux.org>
Sun, 10 May 2009 18:41:11 +0000 (20:41 +0200)
fec.c
fec.h
fecdec_filter.c
http_send.c
net.c
send_common.c
server.c
string.c
write_common.c

diff --git a/fec.c b/fec.c
index fe02487..e4cdbaf 100644 (file)
--- a/fec.c
+++ b/fec.c
@@ -1,5 +1,6 @@
+/** \file fec.c Forward error correction based on Vandermonde matrices. */
+
 /*
- * fec.c -- forward error correction based on Vandermonde matrices
  * 980624
  * (C) 1997-98 Luigi Rizzo (luigi@iet.unipi.it)
  *
@@ -32,6 +33,7 @@
  * OF SUCH DAMAGE.
  */
 
+
 #include "para.h"
 #include "error.h"
 #include "portable_io.h"
diff --git a/fec.h b/fec.h
index 241cf9a..1e28e8a 100644 (file)
--- a/fec.h
+++ b/fec.h
@@ -1,5 +1,6 @@
+/** \file fec.h Exported symbols from fec.c. */
+
 /*
- * fec.c -- forward error correction based on Vandermonde matrices
  * 980614
  * (C) 1997-98 Luigi Rizzo (luigi@iet.unipi.it)
  *
@@ -43,5 +44,3 @@ void fec_encode(struct fec_parms *parms, const unsigned char * const *src,
                unsigned char *dst, int idx, int sz);
 int fec_decode(struct fec_parms *parms, unsigned char **data, int *idx,
                int sz);
-
-
index 103f4ff..a3cba9b 100644 (file)
@@ -78,6 +78,7 @@ struct private_fecdec_data {
        struct fec_parms *fec;
        /** Keeps track of what was received so far. */
        struct fecdec_group groups[NUM_FEC_GROUPS];
+       /** Whether an audio file header was already received. */
        int have_header;
 };
 
index ce308ab..5b98bbf 100644 (file)
@@ -41,7 +41,9 @@ enum http_client_status {
        HTTP_INVALID_GET_REQUEST
 };
 
+/** For each connected client, a structure of this type is maintained. */
 struct private_http_sender_data {
+       /** The current state of this client. */
        enum http_client_status status;
 };
 
diff --git a/net.c b/net.c
index 9579b7d..7207e52 100644 (file)
--- a/net.c
+++ b/net.c
@@ -434,11 +434,31 @@ static char *__get_sock_name(int fd, int (*getname)(int, struct sockaddr*,
        return host_and_port((struct sockaddr *)&ss, sslen);
 }
 
+/**
+ * Look up the local side of a connected socket structure.
+ *
+ * \param sockfd The file descriptor of the socket.
+ *
+ * \return A pointer to a static buffer containing hostname an port. This
+ * buffer must not be freed by the caller.
+ *
+ * \sa remote_name().
+ */
 char *local_name(int sockfd)
 {
        return __get_sock_name(sockfd, getsockname);
 }
 
+/**
+ * Look up the remote side of a connected socket structure.
+ *
+ * \param sockfd The file descriptor of the socket.
+ *
+ * \return Analogous to the return value of \ref local_name() but for the
+ * remote side.
+ *
+ * \sa local_name().
+ */
 char *remote_name(int sockfd)
 {
        return __get_sock_name(sockfd, getpeername);
@@ -456,7 +476,7 @@ struct in_addr extract_v4_addr(const struct sockaddr_storage *ss)
        struct in_addr ia = {.s_addr = 0};
 
        if (ss->ss_family == AF_INET)
-                ia.s_addr = ((struct sockaddr_in *)ss)->sin_addr.s_addr;
+               ia.s_addr = ((struct sockaddr_in *)ss)->sin_addr.s_addr;
        if (ss->ss_family == AF_INET6) {
                const struct in6_addr v6_addr = ((struct sockaddr_in6 *)ss)->sin6_addr;
 
@@ -474,8 +494,8 @@ struct in_addr extract_v4_addr(const struct sockaddr_storage *ss)
  * \param len The length of \a buf.
  *
  * Check if encryption is available. If yes, encrypt the given buffer.  Send
- * out the buffer, encrypted or not, and try to resend the remaing part in case
- * of short writes.
+ * out the buffer, encrypted or not, and try to resend the remaining part in
+ * case of short writes.
  *
  * \return Standard.
  */
index 448ddfe..a2189b0 100644 (file)
@@ -440,6 +440,20 @@ out:
        return ret;
 }
 
+/**
+ * Parse a FEC URL string.
+ *
+ * \param scd The structure containing host, port and the FEC parameters.
+ *
+ * \return Standard.
+ *
+ * A FEC URL consists of an ordinary URL string according to RFC 3986,
+ * optionally followed by a slash and the three FEC parameters slice_size,
+ * data_slices_per_group and slices_per_group. The three FEC parameters are
+ * separated by colons.
+ *
+ * \sa \ref parse_url().
+ */
 int parse_fec_url(const char *arg, struct sender_command_data *scd)
 {
        int ret;
index 9bf6c3f..2e5f5f7 100644 (file)
--- a/server.c
+++ b/server.c
@@ -59,7 +59,7 @@
  *     - Ring buffer: \ref ringbuffer.c, \ref ringbuffer.h,
  *     - Hashing: \ref hash.h, \ref sha1.h, \ref sha1.c,
  *     - Crypto: \ref crypt.c.
- *
+ *     - Forward error correction: \ref fec.c
  */
 
 #include <signal.h>
index eb458da..52003c4 100644 (file)
--- a/string.c
+++ b/string.c
@@ -587,6 +587,13 @@ int para_atoi32(const char *str, int32_t *value)
        return 1;
 }
 
+/**
+ * Compute the loglevel number from its name.
+ *
+ * \param txt The name of the loglevel (debug, info, ...).
+ *
+ * \return The numeric representation of the loglevel name.
+ */
 int get_loglevel_by_name(const char *txt)
 {
        if (!strcasecmp(txt, "debug"))
index 4619d40..316c87e 100644 (file)
@@ -213,7 +213,11 @@ struct writer_node_group *setup_default_wng(void)
        wng->writer_nodes[0].conf = writers[DEFAULT_WRITER].parse_config("");
        return wng;
 }
-
+/**
+ * Print the help text of all writers to stdout.
+ *
+ * \param detailed Whether to print the detailed help text.
+ */
 void print_writer_helps(int detailed)
 {
        int i;