From: Andre Noll <maan@systemlinux.org>
Date: Thu, 15 Jan 2009 03:58:05 +0000 (+0100)
Subject: Add some missing source code documentation.
X-Git-Tag: v0.3.4~75^2~12
X-Git-Url: http://git.tuebingen.mpg.de/?p=paraslash.git;a=commitdiff_plain;h=febf2073674b28f72728dbcac415ea6d7b8cffa3

Add some missing source code documentation.
---

diff --git a/afs.c b/afs.c
index 9ae0650a..b8acb53a 100644
--- a/afs.c
+++ b/afs.c
@@ -1175,6 +1175,16 @@ int com_check(int fd, int argc, char * const * const argv)
 	return 1;
 }
 
+/**
+ * The afs event dispatcher.
+ *
+ * \param event Type of the event.
+ * \param pb May be \p NULL.
+ * \param data Type depends on \a event.
+ *
+ * This function calls the table handlers of all tables and passes \a pb and \a
+ * data verbatim. It's up to the handlers to interpret the \a data pointer.
+ */
 void afs_event(enum afs_events event, struct para_buffer *pb,
 		void *data)
 {
diff --git a/afs.h b/afs.h
index ecec685c..267cc8d3 100644
--- a/afs.h
+++ b/afs.h
@@ -61,14 +61,23 @@ enum afs_events {
 	BLOB_REMOVE,
 };
 
+/**
+ * Used as data for \ref afs_event() for events of type \p ATTRIBUTE_ADD.
+ */
 struct rmatt_event_data {
+	/** The name of the attribute being added. */
 	const char *name;
+	/** Its bit number. */
 	unsigned char bitnum;
 };
 
-
+/**
+ * Used as data for \ref afs_event() for events of type \p ATTRIBUTE_AFSI_CHANGE.
+ */
 struct afsi_change_event_data {
+	/** Pointer to the row that has changed. */
 	struct osl_row *aft_row;
+	/** Afs info before the change. */
 	struct afs_info *old_afsi;
 };
 
diff --git a/aft.c b/aft.c
index 5c0a04bd..7bfad504 100644
--- a/aft.c
+++ b/aft.c
@@ -1008,6 +1008,13 @@ out:
 	return ret;
 }
 
+/**
+ * Write a list of audio-file related status items with empty values.
+ *
+ * \param buf Result pointer.
+ *
+ * This is used by vss when currently no audio file is open.
+ */
 void make_empty_status_items(char *buf)
 {
 	sprintf(buf,
diff --git a/filter.h b/filter.h
index 712f1e5b..2c546c1d 100644
--- a/filter.h
+++ b/filter.h
@@ -197,6 +197,7 @@ struct filter {
 	 */
 	int (*parse_config)(int argc, char **argv, void **config);
 
+	/** The help texts for this filter. */
 	struct ggo_help help;
 };
 
diff --git a/fsck.c b/fsck.c
index bfc178e3..04db5de3 100644
--- a/fsck.c
+++ b/fsck.c
@@ -936,6 +936,14 @@ static int check_all_tables(char *base_dir)
 	return ret;
 }
 
+/**
+ * The praslash database check program.
+ *
+ * \param argc Usual arg count.
+ * \param argv Usual arg vector.
+ *
+ * \return \p EXIT_SUCCESS or \p EXIT_FAILURE.
+ */
 int main(int argc, char **argv)
 {
 	int i, ret;
diff --git a/recv.h b/recv.h
index 74ccf77d..b82e04f5 100644
--- a/recv.h
+++ b/recv.h
@@ -105,6 +105,7 @@ struct receiver {
 	 */
 	void (*post_select)(struct sched *s, struct task *t);
 
+	/** The two help texts of this receiver. */
 	struct ggo_help help;
 };
 
@@ -127,6 +128,7 @@ extern struct receiver receivers[];
 	UDP_RECEIVER \
 	{.name = NULL}};
 
+/** Iterate over all available receivers. */
 #define FOR_EACH_RECEIVER(i) for (i = 0; receivers[i].name; i++)
 
 void *check_receiver_arg(char *ra, int *receiver_num);
diff --git a/recv_common.c b/recv_common.c
index 1df503e4..2840df00 100644
--- a/recv_common.c
+++ b/recv_common.c
@@ -85,6 +85,11 @@ void *check_receiver_arg(char *ra, int *receiver_num)
 	return NULL;
 }
 
+/**
+ * Print out the help texts to all receivers.
+ *
+ * \param detailed Whether the detailed help should be printed.
+ */
 void print_receiver_helps(int detailed)
 {
 	int i;
diff --git a/server.c b/server.c
index 436e72af..2c2f31c1 100644
--- a/server.c
+++ b/server.c
@@ -198,6 +198,14 @@ err_out:
 	exit(EXIT_FAILURE);
 }
 
+/**
+ * (Re-)read the server configuration files.
+ *
+ * \param override Passed to gengetopt to activate the override feature.
+ *
+ * This function also re-opens the logfile and sets the global \a
+ * user_list_file variable.
+ */
 void parse_config_or_die(int override)
 {
 	char *home = para_homedir();
diff --git a/udp_send.c b/udp_send.c
index b0f55bc3..3804c39c 100644
--- a/udp_send.c
+++ b/udp_send.c
@@ -68,6 +68,7 @@ static void udp_delete_target(struct udp_target *ut, const char *msg)
 	free(ut);
 }
 
+/** The maximal size of the per-target chunk queue. */
 #define UDP_CQ_BYTES 40000
 
 static int udp_init_session(struct udp_target *ut)