From: Andre Noll <maan@systemlinux.org>
Date: Sun, 10 May 2009 18:41:11 +0000 (+0200)
Subject: Add some missing source code documentation.
X-Git-Tag: v0.3.5~52
X-Git-Url: http://git.tuebingen.mpg.de/?p=paraslash.git;a=commitdiff_plain;h=f8f6605a4f02a15378a36618dbfacfc862fc6192

Add some missing source code documentation.
---

diff --git a/fec.c b/fec.c
index fe02487d..e4cdbaf3 100644
--- 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 241cf9a4..1e28e8a4 100644
--- 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);
-
-
diff --git a/fecdec_filter.c b/fecdec_filter.c
index 103f4ffc..a3cba9bb 100644
--- a/fecdec_filter.c
+++ b/fecdec_filter.c
@@ -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;
 };
 
diff --git a/http_send.c b/http_send.c
index ce308ab7..5b98bbf4 100644
--- a/http_send.c
+++ b/http_send.c
@@ -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 9579b7df..7207e528 100644
--- 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.
  */
diff --git a/send_common.c b/send_common.c
index 448ddfec..a2189b03 100644
--- a/send_common.c
+++ b/send_common.c
@@ -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;
diff --git a/server.c b/server.c
index 9bf6c3f8..2e5f5f74 100644
--- 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>
diff --git a/string.c b/string.c
index eb458dad..52003c4b 100644
--- 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"))
diff --git a/write_common.c b/write_common.c
index 4619d407..316c87ef 100644
--- a/write_common.c
+++ b/write_common.c
@@ -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;