Add doxygen comments for various structs.
authorAndre Noll <maan@systemlinux.org>
Fri, 26 Oct 2007 15:26:04 +0000 (17:26 +0200)
committerAndre Noll <maan@systemlinux.org>
Fri, 26 Oct 2007 15:26:04 +0000 (17:26 +0200)
afs.c
afs.h
aft.c
attribute.c
mood.c
ortp_send.c
write.c

diff --git a/afs.c b/afs.c
index c36f86b..20f2455 100644 (file)
--- 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 bebe3ea..9e1f61e 100644 (file)
--- 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 5c16052..c99b5ac 100644 (file)
--- 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;
 };
 
index 6740e47..3acbadb 100644 (file)
@@ -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 d6040f1..4988c68 100644 (file)
--- 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;
 };
 
index 084fdf5..0c6cccb 100644 (file)
 #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 93c63c8..7b95d6b 100644 (file)
--- 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>
 #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.