From 1f31b52b6816ce2716a3755a1896f77744fa167b Mon Sep 17 00:00:00 2001 From: Andre Noll Date: Fri, 26 Oct 2007 03:58:21 +0200 Subject: [PATCH] More Documentation improvments. --- afh.h | 4 ++-- aft.c | 16 +++++++++++++++- audiod.c | 2 +- blob.c | 5 +++++ mp3dec.c | 27 +++++++++++---------------- oggdec.c | 23 ++++++++++++----------- 6 files changed, 46 insertions(+), 31 deletions(-) diff --git a/afh.h b/afh.h index 1e37c9c3..504bc2b2 100644 --- a/afh.h +++ b/afh.h @@ -23,7 +23,7 @@ /** \endcond */ -/** size of the audio_file info string */ +/** Size of the audio_file info string. */ #define AUDIO_FILE_INFO_SIZE 256 /** Audio format dependent information. */ @@ -58,7 +58,7 @@ struct afh_info { unsigned header_offset; /** The number of channels. */ uint8_t channels; - /** Frquency on Hz. */ + /** Frequency in Hz. */ uint16_t frequency; /** Exact meaning depends on audio format. */ uint16_t bitrate; diff --git a/aft.c b/aft.c index 13e23748..5c160520 100644 --- a/aft.c +++ b/aft.c @@ -110,16 +110,27 @@ struct ls_data { HASH_TYPE *hash; }; +/** Data passed from the ls command handler to its callback function. */ struct ls_options { + /** The given command line flags. */ unsigned flags; + /** The sorting method given at the command line. */ enum ls_sorting_method sorting; + /** The given listing mode (short, long, verbose, mbox). */ enum ls_listing_mode mode; + /** The arguments passed to the ls command. */ char **patterns; + /** Number of non-option arguments. */ int num_patterns; + /** Used for long listing mode to align the output fields. */ struct ls_widths widths; + /** Size of the \a data array. */ uint32_t array_size; + /** Number of used entries in the data array. */ uint32_t num_matching_paths; + /** Array of matching entries. */ struct ls_data *data; + /** Used to sort the array. */ struct ls_data **data_ptr; }; @@ -1571,8 +1582,11 @@ out: return 1; } +/** Used by com_add(). */ struct private_add_data { + /** The socket file descriptor. */ int fd; + /** The given add flags. */ uint32_t flags; }; @@ -2254,7 +2268,7 @@ int aft_check_callback(__a_unused const struct osl_object *query, struct osl_obj /** * Close the audio file table. * - * \param flags Ususal flags that are passed to osl_close_table(). + * \param flags Usual flags that are passed to osl_close_table(). * * \sa osl_close_table(). */ diff --git a/audiod.c b/audiod.c index 58d65275..38aa5aaf 100644 --- a/audiod.c +++ b/audiod.c @@ -33,7 +33,7 @@ INIT_AUDIOD_ERRLISTS; /** define the array containing all supported audio formats */ const char *audio_formats[] = {AUDIOD_AUDIO_FORMAT_ARRAY NULL}; -/** defines how to handle one supported audio format */ +/** Defines how audiod handles one supported audio format. */ struct audio_format_info { /** pointer to the receiver for this audio format */ struct receiver *receiver; diff --git a/blob.c b/blob.c index 72e4a55b..a5ea93aa 100644 --- a/blob.c +++ b/blob.c @@ -54,7 +54,9 @@ enum blob_ls_flags { /** Structure passed to the \p print_blob function. */ struct lsblob_action_data { + /* The flags given at the command line. */ uint32_t flags; + /** Message buffer. */ struct para_buffer pb; }; @@ -205,8 +207,11 @@ static int com_catblob(callback_function *f, int fd, int argc, return ret; } +/** Used for removing rows from a blob table. */ struct rmblob_data { + /** Message buffer. */ struct para_buffer pb; + /** Number of removed blobs. */ unsigned num_removed; }; diff --git a/mp3dec.c b/mp3dec.c index 5c6bab33..16599411 100644 --- a/mp3dec.c +++ b/mp3dec.c @@ -4,7 +4,7 @@ * Licensed under the GPL v2. For licencing details see COPYING. */ -/** \file mp3dec.c paraslash's mp3 decoder */ +/** \file mp3dec.c Paraslash's mp3 decoder. */ #include "para.h" #include "list.h" @@ -14,25 +14,20 @@ #include #include "string.h" -/** the output buffer size */ -#define MP3_OUTBUF_SIZE 128 * 1024 +/** The output buffer size. */ +#define MP3_OUTBUF_SIZE (128 * 1024) -/** \cond a helper macro */ +/** Convert a sample value from libmad to a signed short. */ #define MAD_TO_SHORT(f) (f) >= MAD_F_ONE? SHRT_MAX :\ (f) <= -MAD_F_ONE? -SHRT_MAX : (signed short) ((f) >> (MAD_F_FRACBITS - 15)) -/** \endcond */ -/** - * data specific to the mp3dec filter - * - * \sa filter, filter_node - */ +/** Data specific to the mp3dec filter. */ struct private_mp3dec_data { - /** information on the current mp3 stream */ + /** Information on the current mp3 stream. */ struct mad_stream stream; - /** information about the frame which is currently decoded */ + /** Information about the frame which is currently decoded. */ struct mad_frame frame; - /** contains the PCM output */ + /** Contains the PCM output. */ struct mad_synth synth; }; @@ -115,11 +110,11 @@ static void mp3dec_open(struct filter_node *fn) } /** - * the init function of the mp3dec filter + * The init function of the mp3dec filter. * - * \param f pointer to the filter struct to initialize + * \param f Pointer to the filter struct to initialize. * - * \sa filter::init + * \sa filter::init. */ void mp3dec_init(struct filter *f) { diff --git a/oggdec.c b/oggdec.c index 54586b58..3dced8a0 100644 --- a/oggdec.c +++ b/oggdec.c @@ -17,25 +17,22 @@ #include -/** \cond some internal constants */ -#define BITS 16 +/** Determine byte sex. */ #ifdef WORDS_BIGENDIAN #define ENDIAN 1 #else #define ENDIAN 0 #endif -#define SIGN 1 -/** \endcond */ -/** data specific to the oggdec filter */ +/** Data specific to the oggdec filter. */ struct private_oggdec_data { - /** describes an ogg vorbis file */ + /** Describes an ogg vorbis file. */ OggVorbis_File *vf; - /** the input buffer */ + /** The input buffer. */ char *inbuf; - /** the length of \a inbuf */ + /** The length of \a inbuf. */ size_t inbuf_len; - /** the number of bytes consumed from the input buffer */ + /** The number of bytes consumed from the input buffer. */ size_t converted; }; @@ -155,7 +152,7 @@ static ssize_t ogg_convert(char *inbuffer, size_t len, struct filter_node *fn) while (!*fn->fc->input_eof && fn->loaded < fn->bufsize) { int length = fn->bufsize - fn->loaded; long read_ret = ov_read(pod->vf, fn->buf + fn->loaded, length, - ENDIAN, BITS / 8, SIGN, NULL); + ENDIAN, 2 /* 16 bit */, 1 /* signed */, NULL); if (read_ret == OV_HOLE || !read_ret) return pod->converted; if (read_ret < 0) @@ -174,7 +171,11 @@ static void *oggdec_parse_config(int argc, char **argv) return NULL; } -/** the init function of the ogg vorbis decoder */ +/** + * The init function of the ogg vorbis decoder. + * + * \param f Its fields are filled in by the function. + */ void oggdec_init(struct filter *f) { f->open = ogg_open; -- 2.39.2