More Documentation improvments.

diff --git a/afh.h b/afh.h
index 1e37c9c39c26a328c6663e8108f9ff2d071ff4a2..504bc2b213b70b4d053fba486e84cacf59c0b074 100644 (file)
--- 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 13e237484a1367cd21d41b18dd2670c15104b421..5c1605207f67cb114b7e7d6d4add234824bc3af5 100644 (file)
--- 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 58d65275c6b9cb0b31017ec233b68d69502e7435..38aa5aafba75bcf7c67418ab7035f9eb0dbe11ff 100644 (file)
--- 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 72e4a55b30ffe4ca3e13a79f866f7f2a27f67baf..a5ea93aa9ffbb29fe6171bcf7dc28649ec081e3f 100644 (file)
--- 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 5c6bab339e599152ccbba81d4873500fd8af7e3a..16599411820313eae492a604fb58d09b1221b752 100644 (file)
--- 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 <mad.h>
 #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 54586b581da2b061bde62cf7a55e60a8deaffea6..3dced8a0baf58baf6617498c481668944e5ad183 100644 (file)
--- a/oggdec.c
+++ b/oggdec.c
@@ -17,25 +17,22 @@
 
 #include <vorbis/vorbisfile.h>
 
-/** \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;