From a5b65db9da1cd81c25494429ea8adb5d76e5b32a Mon Sep 17 00:00:00 2001 From: Andre Noll Date: Fri, 26 Oct 2007 17:26:04 +0200 Subject: [PATCH] Add doxygen comments for various structs. --- afs.c | 4 ++++ afs.h | 5 ----- aft.c | 36 +++++++++++++++++++++++++++--------- attribute.c | 11 ++++++++++- mood.c | 3 +++ ortp_send.c | 21 ++++++++++----------- write.c | 38 ++++++++++++++++---------------------- 7 files changed, 70 insertions(+), 48 deletions(-) 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 #include @@ -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. -- 2.39.5