From: Andre Noll <maan@systemlinux.org>
Date: Fri, 26 Oct 2007 15:26:04 +0000 (+0200)
Subject: Add doxygen comments for various structs.
X-Git-Tag: v0.3.0~182
X-Git-Url: http://git.tuebingen.mpg.de/?p=paraslash.git;a=commitdiff_plain;h=a5b65db9da1cd81c25494429ea8adb5d76e5b32a;hp=f21c1d61efaab276b6dd65e122d18ca0b859c8b5

Add doxygen comments for various structs.
---

diff --git a/afs.c b/afs.c
index c36f86b8..20f2455e 100644
--- a/afs.c
+++ b/afs.c
@@ -754,9 +754,13 @@ static void register_signal_task(void)
 
 static struct list_head afs_client_list;
 
+/** Describes on connected afs client. */
 struct afs_client {
+	/** Position in the afs client list. */
 	struct list_head node;
+	/** The socket file descriptor for this client. */
 	int fd;
+	/** The time the client connected. */
 	struct timeval connect_time;
 };
 
diff --git a/afs.h b/afs.h
index bebe3ea3..9e1f61e0 100644
--- a/afs.h
+++ b/afs.h
@@ -65,11 +65,6 @@ struct rmatt_event_data {
 };
 
 
-struct addatt_event_data {
-	const char *name;
-	unsigned char bitnum;
-};
-
 struct afsi_change_event_data {
 	const struct osl_row *aft_row;
 	struct afs_info *old_afsi;
diff --git a/aft.c b/aft.c
index 5c160520..c99b5ac5 100644
--- a/aft.c
+++ b/aft.c
@@ -1221,12 +1221,8 @@ out:
 }
 
 /*
- * TODO: flags -h (sort by hash) -lm (list in mbox format)
- *
- * long list: list hash, attributes as (xx--x-x-), file size, lastplayed
- * full list: list everything, including afsi, afhi, atts as clear text
- *
- * */
+ * TODO: flags -h (sort by hash)
+ */
 int com_ls(int fd, int argc, char * const * const argv)
 {
 	int i, ret;
@@ -1793,16 +1789,25 @@ enum touch_flags {
 	TOUCH_FLAG_VERBOSE = 2
 };
 
+/** Options used by com_touch(). */
 struct com_touch_options {
+	/** New num_played value. */
 	int32_t num_played;
+	/** New last played count. */
 	int64_t last_played;
+	/** new lyrics id. */
 	int32_t lyrics_id;
+	/** new image id. */
 	int32_t image_id;
+	/** command line flags (see \ref touch_flags). */
 	unsigned flags;
 };
 
+/** Data passed to the action handler of com_touch(). */
 struct touch_action_data {
+	/** Command line options (see \ref com_touch_options). */
 	struct com_touch_options *cto;
+	/** Message buffer. */
 	struct para_buffer pb;
 };
 
@@ -1947,22 +1952,30 @@ int com_touch(int fd, int argc, char * const * const argv)
 	return ret;
 }
 
+/** Flags for com_rm(). */
 enum rm_flags {
+	/** -v */
 	RM_FLAG_VERBOSE = 1,
+	/** -f */
 	RM_FLAG_FORCE = 2,
+	/** -p */
 	RM_FLAG_FNM_PATHNAME = 4
 };
 
-struct com_rm_data {
+/** Data passed to the action handler of com_rm(). */
+struct com_rm_action_data {
+	/** Command line flags ((see \ref rm_flags). */
 	uint32_t flags;
+	/** Message buffer. */
 	struct para_buffer pb;
+	/** Number of audio files removed. */
 	unsigned num_removed;
 };
 
 static int remove_audio_file(__a_unused struct osl_table *table,
 		struct osl_row *row, const char *name, void *data)
 {
-	struct com_rm_data *crd = data;
+	struct com_rm_action_data *crd = data;
 	int ret;
 
 	if (crd->flags & RM_FLAG_VERBOSE)
@@ -1979,7 +1992,7 @@ static int remove_audio_file(__a_unused struct osl_table *table,
 static int com_rm_callback(const struct osl_object *query,
 		__a_unused struct osl_object *result)
 {
-	struct com_rm_data crd = {.flags = *(uint32_t *)query->data};
+	struct com_rm_action_data crd = {.flags = *(uint32_t *)query->data};
 	int ret;
 	struct pattern_match_data pmd = {
 		.table = audio_file_table,
@@ -2071,10 +2084,15 @@ enum cpsi_flags {
 	CPSI_FLAG_VERBOSE = 32,
 };
 
+/** Data passed to the action handler of com_cpsi(). */
 struct cpsi_action_data {
+	/** command line flags (see \ref cpsi_flags). */
 	unsigned flags;
+	/** Number of audio files changed. */
 	unsigned num_copied;
+	/** Message buffer. */
 	struct para_buffer pb;
+	/** Values are copied from here. */
 	struct afs_info source_afsi;
 };
 
diff --git a/attribute.c b/attribute.c
index 6740e474..3acbadbe 100644
--- a/attribute.c
+++ b/attribute.c
@@ -279,6 +279,12 @@ int com_setatt(__a_unused int fd, int argc, char * const * const argv)
 		NULL);
 }
 
+struct addatt_event_data {
+	const char *name;
+	unsigned char bitnum;
+};
+
+
 static int com_addatt_callback(const struct osl_object *query,
 		struct osl_object *result)
 {
@@ -409,10 +415,13 @@ int com_mvatt(int fd, int argc, char * const * const argv)
 	return ret;
 }
 
-
+/** Data passed to the action handler of com_rmatt(). */
 struct remove_attribute_action_data {
+	/** Message buffer. */
 	struct para_buffer pb;
+	/** Numver of attributes removed. */
 	int num_removed;
+	/** Bitwise "or" of the removed attributes. */
 	uint64_t mask_of_removed_atts;
 };
 
diff --git a/mood.c b/mood.c
index d6040f15..4988c685 100644
--- a/mood.c
+++ b/mood.c
@@ -372,8 +372,11 @@ enum mood_line_type {
 	ML_SCORE
 };
 
+/** Data passed to the parser of a mood line. */
 struct mood_line_parser_data {
+	/** The mood this mood line belongs to. */
 	struct mood *m;
+	/** The line number in the mood definition. */
 	unsigned line_num;
 };
 
diff --git a/ortp_send.c b/ortp_send.c
index 084fdf57..0c6cccb9 100644
--- a/ortp_send.c
+++ b/ortp_send.c
@@ -21,27 +21,26 @@
 #include "list.h"
 #include "ortp.h"
 
-/** \cond convert in_addr to ascii */
+/** Convert in_addr to ascii. */
 #define TARGET_ADDR(oc) inet_ntoa((oc)->addr)
-/** \endcond */
 
-/** describes one entry in the list of targets for the ortp sender */
+/** Describes one entry in the list of targets for the ortp sender. */
 struct ortp_target {
-/** address info */
+	/** Address info. */
 	struct in_addr addr;
-/** whether the ortp sender is activated */
+	/** Whether the ortp sender is activated. */
 	int status;
-/** the ortp timestamp increases by this amount */
+	/** The ortp timestamp increases by this amount. */
 	uint32_t chunk_ts;
-/** the currently used timestamp for this target */
+	/** The currently used timestamp for this target. */
 	uint32_t last_ts;
-/** the position of this target in the list of targets */
+	/** The position of this target in the list of targets. */
 	struct list_head node;
-/** the UDP port */
+	/** The UDP port. */
 	int port;
-/** non-zero if at least one chunk has been sent to this target */
+	/** Non-zero if at least one chunk has been sent to this target. */
 	int streaming;
-/** the session pointer from libortp */
+	/** The session pointer from libortp. */
 	RtpSession *session;
 };
 
diff --git a/write.c b/write.c
index 93c63c8d..7b95d6b3 100644
--- a/write.c
+++ b/write.c
@@ -4,7 +4,7 @@
  * Licensed under the GPL v2. For licencing details see COPYING.
  */
 
-/** \file write.c Paraslash's standalone wav/raw player */
+/** \file write.c Paraslash's standalone wav/raw player. */
 
 #include <sys/types.h>
 #include <dirent.h>
@@ -20,35 +20,29 @@
 #include "fd.h"
 #include "error.h"
 
-/** \cond */
 INIT_WRITE_ERRLISTS;
-/** \endcond */
 
-/**
- * check if given buffer contains a valid wave header
- */
+/** Check if given buffer contains a valid wave header. */
 struct check_wav_task {
-	/** the buffer to check */
+	/** The buffer to check. */
 	char *buf;
-	/** number of bytes loaded in \a buf */
+	/** Number of bytes loaded in \a buf. */
 	size_t *loaded;
-	/** non-zero if end of file was reached */
+	/** Non-zero if end of file was reached. */
 	int *eof;
-	/** number of channels specified in wav header given by \a buf */
+	/** Number of channels specified in wav header given by \a buf. */
 	unsigned channels;
-	/** samplerate specified in wav header given by \a buf */
+	/** Samplerate specified in wav header given by \a buf. */
 	unsigned samplerate;
-	/** the task structure for this task */
+	/** The task structure for this task. */
 	struct task task;
 };
 
-/**
- * delay writing until given time
- */
+/** Delay writing until given time. */
 struct initial_delay_task {
-	/** the time the first data should be written out */
+	/** The time the first data should be written out. */
 	struct timeval start_time;
-	/** the task structure for this task */
+	/** The task structure for this task. */
 	struct task task;
 };
 
@@ -58,11 +52,11 @@ static struct check_wav_task cwt;
 static struct initial_delay_task idt;
 static struct writer_node_group *wng;
 
-/** length of a standard wav header */
+/** Length of a standard wav header. */
 #define WAV_HEADER_LEN 44
 
 /**
- * test if audio buffer contains a valid wave header
+ * Test if audio buffer contains a valid wave header.
  *
  * \return If not, return -E_NO_WAV_HEADER, otherwise, return zero. If
  * there is less than WAV_HEADER_LEN bytes awailable, return one.
@@ -207,10 +201,10 @@ static void cwt_event_handler(struct task *t)
 }
 
 /**
- * para_write's main function
+ * Para_write's main function.
  *
- * \param argc the usual argument counter
- * \param argv the usual argument vector
+ * \param argc The usual argument counter.
+ * \param argv The usual argument vector.
  *
  * It registers the stdin task, the check_wav_task, the task for initial delay
  * and all tasks for actually writing out the stream.