Add more documentation.
authorAndre Noll <maan@systemlinux.org>
Sat, 6 Oct 2007 17:00:24 +0000 (19:00 +0200)
committerAndre Noll <maan@systemlinux.org>
Sat, 6 Oct 2007 17:00:24 +0000 (19:00 +0200)
12 files changed:
afs.c
afs.h
aft.c
attribute.c
hash.h
net.c
para.h
playlist.c
portable_io.h
string.c
string.h
write.c

diff --git a/afs.c b/afs.c
index de713fa..a3b8d88 100644 (file)
--- a/afs.c
+++ b/afs.c
@@ -123,7 +123,7 @@ struct callback_result {
 };
 
 /**
- * Ask the parent process to call a given function.
+ * Ask the afs process to call a given function.
  *
  * \param f The function to be called.
  * \param query Pointer to arbitrary data for the callback.
@@ -307,6 +307,14 @@ static int action_if_pattern_matches(struct osl_row *row, void *data)
        return 1;
 }
 
+/**
+ * Execute the given function for each matching row.
+ *
+ * \param pmd Describes what to match and how.
+ *
+ * \return The return value of the underlying call to osl_rbtree_loop()
+ * or osl_rbtree_loop_reverse().
+ */
 int for_each_matching_row(struct pattern_match_data *pmd)
 {
        if (pmd->pm_flags & PM_REVERSE_LOOP)
@@ -737,10 +745,11 @@ static void execute_afs_command(int fd, uint32_t expected_cookie)
                        query_shmid);
                return;
        }
-       /* Ignore return value: Errors might be ok here. */
+       /* Ignore return value: Errors might be OK here. */
        call_callback(fd, query_shmid);
 }
 
+/** Shutdown connection if query has not arrived until this many seconds. */
 #define AFS_CLIENT_TIMEOUT 3
 
 static void command_post_select(struct sched *s, struct task *t)
@@ -753,7 +762,7 @@ static void command_post_select(struct sched *s, struct task *t)
        list_for_each_entry_safe(client, tmp, &afs_client_list, node) {
                if (FD_ISSET(client->fd, &s->rfds))
                        execute_afs_command(client->fd, ct->cookie);
-               else { /* prevent bogus connection flodding */
+               else { /* prevent bogus connection flooding */
                        struct timeval diff;
                        tv_diff(now, &client->connect_time, &diff);
                        if (diff.tv_sec < AFS_CLIENT_TIMEOUT)
@@ -793,13 +802,19 @@ static void register_command_task(uint32_t cookie)
        register_task(&ct->task);
 }
 
-void register_tasks(uint32_t cookie)
+static void register_tasks(uint32_t cookie)
 {
        register_signal_task();
        register_command_task(cookie);
 }
 
-__noreturn int afs_init(uint32_t cookie, int socket_fd)
+/**
+ * Initialize the audio file selector process.
+ *
+ * \param cookie The value used for "authentication".
+ * \param socket_fd File descriptor used for communication with the server.
+ */
+__noreturn void afs_init(uint32_t cookie, int socket_fd)
 {
        enum play_mode current_play_mode;
        struct sched s;
@@ -881,9 +896,17 @@ int com_init(int fd, int argc, char * const * const argv)
        return send_va_buffer(fd, "successfully created afs table(s)\n");
 }
 
+/**
+ * Flags for the check command.
+ *
+ * \sa com_check().
+ */
 enum com_check_flags {
+       /** Check the audio file table. */
        CHECK_AFT = 1,
+       /** Check the mood table. */
        CHECK_MOODS = 2,
+       /** Check the playlist table. */
        CHECK_PLAYLISTS = 4
 };
 
diff --git a/afs.h b/afs.h
index 7167da4..ab2db3a 100644 (file)
--- a/afs.h
+++ b/afs.h
@@ -4,6 +4,8 @@
  * Licensed under the GPL v2. For licencing details see COPYING.
  */
 
+/** \file afs.h Exported symbos of the audio file selector. */
+
 #include <regex.h>
 #include "osl.h"
 #include "hash.h"
@@ -42,26 +44,39 @@ struct audio_file_data {
        struct osl_object map;
 };
 
+/** Flags passed to for_each_matching_row(). */
 enum pattern_match_flags {
+       /** Loop in reverse order. */
        PM_REVERSE_LOOP = 1,
+       /** If no pattern is given, loop over all rows. */
        PM_NO_PATTERN_MATCHES_EVERYTHING = 2,
+       /** If the data in match_column is the empty string, skip this row. */
        PM_SKIP_EMPTY_NAME = 4,
 };
 
+/** Structure passed to for_each_matching_row(). */
 struct pattern_match_data {
+       /** Loop over all rows in this table. */
        struct osl_table *table;
+       /** Determines the loop order. Must be an rbtree column. */
        unsigned loop_col_num;
+       /** Data from this column is matched against the given patterns. */
        unsigned match_col_num;
+       /** \see pattern_match_flags. */
        unsigned pm_flags;
+       /** This value is passed verbatim to fnmatch(). */
        int fnmatch_flags;
+       /** Null-terminated array of patterns. */
        struct osl_object patterns;
+       /** Data pointer passed to the action function. */
        void *data;
+       /** For each matching row, this function will be called. */
        int (*action)(struct osl_table *table, struct osl_row *row, const char *name, void *data);
 };
 
 /* afs */
 typedef int callback_function(const struct osl_object *, struct osl_object *);
-__noreturn int afs_init(uint32_t cookie, int socket_fd);
+__noreturn void afs_init(uint32_t cookie, int socket_fd);
 int send_callback_request(callback_function *f, struct osl_object *query,
        struct osl_object *result);
 int send_standard_callback_request(int argc, char * const * const argv,
diff --git a/aft.c b/aft.c
index 431bedb..c6ca289 100644 (file)
--- a/aft.c
+++ b/aft.c
@@ -298,12 +298,19 @@ bad_path:
        return -E_BAD_PATH;
 }
 
+/** The on-disk layout of a afhi struct. */
 enum afhi_offsets {
+       /** Where the number of seconds is stored. */
        AFHI_SECONDS_TOTAL_OFFSET = 0,
+       /** Position of the bitrate. */
        AFHI_BITRATE_OFFSET = 4,
+       /** Position of the frequency. */
        AFHI_FREQUENCY_OFFSET = 8,
+       /** Number of channels is stored here. */
        AFHI_CHANNELS_OFFSET = 12,
+       /** The tag info position. */
        AFHI_INFO_STRING_OFFSET = 13,
+       /** Minimal on-disk size of a valid afhi struct. */
        MIN_AFHI_SIZE = 14
 };
 
@@ -670,6 +677,7 @@ static int get_local_time(uint64_t *seconds, char *buf, size_t size,
        return 1;
 }
 
+/** Compute the number of (decimal) digits of a number. */
 #define GET_NUM_DIGITS(x, num) { \
        typeof((x)) _tmp = PARA_ABS(x); \
        *num = 1; \
@@ -1363,13 +1371,17 @@ afhi <=> force or no HS
 
 */
 
-
-#define ADD_FLAG_LAZY 1
-#define ADD_FLAG_FORCE 2
-#define ADD_FLAG_VERBOSE 4
-#define ADD_FLAG_ALL 8
-
-/* TODO: change log messages so that they get written to the result buffer */
+/** Flags passed to the add command. */
+enum com_add_flags {
+       /** Skip paths that exist already. */
+       ADD_FLAG_LAZY = 1,
+       /** Force adding. */
+       ADD_FLAG_FORCE = 2,
+       /** Print what is being done. */
+       ADD_FLAG_VERBOSE = 4,
+       /** Try to add files with unknown suffixes. */
+       ADD_FLAG_ALL = 8,
+};
 
 static int com_add_callback(const struct osl_object *query,
                struct osl_object *result)
@@ -1683,8 +1695,15 @@ int com_add(int fd, int argc, char * const * const argv)
 
 }
 
+/**
+ * Flags used by the touch command.
+ *
+ * \sa com_touch().
+ */
 enum touch_flags {
+       /** Whether the \p FNM_PATHNAME flag should be passed to fnmatch(). */
        TOUCH_FLAG_FNM_PATHNAME = 1,
+       /** Activates verbose mode. */
        TOUCH_FLAG_VERBOSE = 2
 };
 
@@ -1947,12 +1966,23 @@ int com_afs_rm(int fd, int argc,  char * const * const argv)
        return ret;
 }
 
+/**
+ * Flags used by the cpsi command.
+ *
+ * \sa com_cpsi().
+ */
 enum cpsi_flags {
+       /** Whether the lyrics id should be copied. */
        CPSI_FLAG_COPY_LYRICS_ID = 1,
+       /** Whether the image id should be copied. */
        CPSI_FLAG_COPY_IMAGE_ID = 2,
+       /** Whether the lastplayed time should be copied. */
        CPSI_FLAG_COPY_LASTPLAYED = 4,
+       /** Whether the numplayed count should be copied. */
        CPSI_FLAG_COPY_NUMPLAYED = 8,
+       /** Whether the attributes should be copied. */
        CPSI_FLAG_COPY_ATTRIBUTES = 16,
+       /** Activates verbose mode. */
        CPSI_FLAG_VERBOSE = 32,
 };
 
@@ -2123,6 +2153,16 @@ static int check_audio_file(struct osl_row *row, void *data)
        return 1;
 }
 
+/**
+ * Check the audio file table for inconsistencies.
+ *
+ * \param query Unused.
+ * \param result Contains message string upon return.
+ *
+ * This function always succeeds.
+ *
+ * \sa com_check().
+ */
 int aft_check_callback(__a_unused const struct osl_object *query, struct osl_object *result)
 {
        struct para_buffer pb = {.buf = NULL};
@@ -2135,8 +2175,6 @@ int aft_check_callback(__a_unused const struct osl_object *query, struct osl_obj
 
 }
 
-
-
 /**
  * Close the audio file table.
  *
index 671ca05..d34f7d6 100644 (file)
@@ -99,11 +99,17 @@ int get_attribute_bitnum_by_name(const char *att_name, unsigned char *bitnum)
        return 1;
 }
 
+/**
+ * Flags used by the lsatt command.
+ *
+ * \param \sa com_lsatt().
+ */
 enum lsatt_flags {
        /** Whether "-a" was given for the lsatt command. */
        LSATT_FLAG_SORT_BY_ID = 1,
        /** Whether "-l" was given for the lsatt command. */
        LSATT_FLAG_LONG = 2,
+       /** Reverse sort order. */
        LSATT_FLAG_REVERSE = 4
 };
 
diff --git a/hash.h b/hash.h
index 99f4486..51028c4 100644 (file)
--- a/hash.h
+++ b/hash.h
@@ -1,12 +1,30 @@
+/*
+ * Copyright (C) 2007 Andre Noll <maan@systemlinux.org>
+ *
+ * Licensed under the GPL v2. For licencing details see COPYING.
+ */
+
+/** \file hash.h Inline functions for hash values. */
+
 #include "portable_io.h"
+
+/** hash arrays are always unsigned char. */
 #define HASH_TYPE unsigned char
 
-//#include "super_fast_hash.h"
-//#define hash_function super_fast_hash
 #include "sha1.h"
+/** We use openssl's sha1 implementation. */
 #define hash_function sha1_hash
 
-static inline int hash_compare(HASH_TYPE *h1, HASH_TYPE *h2)
+/**
+ * Compare two hashes.
+ *
+ * \param h1 Pointer to the first hash value.
+ * \param h2 Pointer to the second hash value.
+ *
+ * \return 1, -1, or zero, depending on whether \a h1 is greater than,
+ * less than or equal to h2, respectively.
+ */
+_static_inline_ int hash_compare(HASH_TYPE *h1, HASH_TYPE *h2)
 {
        int i;
 
@@ -19,7 +37,17 @@ static inline int hash_compare(HASH_TYPE *h1, HASH_TYPE *h2)
        return 0;
 }
 
-static inline void hash_to_asc(HASH_TYPE *hash, char *asc)
+/**
+ * Convert a hash value to ascii format.
+ *
+ * \param hash the hash value.
+ * \param asc Result pointer.
+ *
+ * \a asc must point to an area of at least 2 * \p HASH_SIZE + 1 bytes which
+ * will be filled by the function with the ascii representation of the hash
+ * value given by \a hash, and a terminating \p NULL byte.
+ */
+_static_inline_ void hash_to_asc(HASH_TYPE *hash, char *asc)
 {
        int i;
        const char hexchar[] = "0123456789abcdef";
diff --git a/net.c b/net.c
index 0e41be1..9a93553 100644 (file)
--- a/net.c
+++ b/net.c
@@ -284,14 +284,16 @@ int get_host_info(char *host, struct hostent **ret)
 }
 
 /**
- * a wrapper around socket(2)
+ * A wrapper around socket(2).
  *
- * Create an IPv4 socket for sequenced, reliable, two-way, connection-based
- * byte streams.
+ * \param domain The communication domain that selects the protocol family.
  *
  * \return The socket fd on success, -E_SOCKET on errors.
  *
- * \sa socket(2)
+ * Create an IPv4 socket for sequenced, reliable, two-way, connection-based
+ * byte streams.
+ *
+ * \sa socket(2).
  */
 int get_stream_socket(int domain)
 {
diff --git a/para.h b/para.h
index 5dec070..dea9291 100644 (file)
--- a/para.h
+++ b/para.h
 /** last message before exit */
 #define EMERG 7
 
-/** log messages with lower proirity than that will not be compiled in*/
+/** Log messages with lower priority than that will not be compiled in. */
 #define COMPILE_TIME_LOGLEVEL 0
 
+/** \cond */
 #if DEBUG > COMPILE_TIME_LOGLEVEL
 #define PARA_DEBUG_LOG(f,...) para_log(DEBUG, "%s: " f, __FUNCTION__, ## __VA_ARGS__)
 #else
@@ -96,6 +97,7 @@
 #else
 #define PARA_EMERG_LOG(...)
 #endif
+/** \endcond */
 
 /**
  * define a standard log function that always writes to stderr
@@ -173,11 +175,18 @@ int stat_item_valid(const char *item);
 int stat_line_valid(const char *);
 void stat_client_write(const char *msg, int itemnum);
 int stat_client_add(int fd, long unsigned mask);
+/** Loop over each status item. */
 #define FOR_EACH_STAT_ITEM(i) for (i = 0; i < NUM_STAT_ITEMS; i++)
 
 __printf_2_3 void para_log(int, const char*, ...);
 
-/* taken from printf man page */
+/**
+ * Write a log message to a dynamically allocated string.
+ *
+ * \param fmt Usual format string.
+ * \param p Result pointer.
+ *
+ * \sa printf(3). */
 #define PARA_VSPRINTF(fmt, p) \
 { \
        int n; \
@@ -201,6 +210,13 @@ __printf_2_3 void para_log(int, const char*, ...);
        } \
 }
 
+/**
+ *  Return a random non-negative integer in an interval.
+ *
+ * \param max Determines maximal possible return value.
+ *
+ * \return An integer between zero and \p max - 1, inclusively.
+ */
 static inline int para_random(unsigned max)
 {
        return ((max + 0.0) * (rand() / (RAND_MAX + 1.0)));
index 6f9f966..ba99fad 100644 (file)
@@ -122,6 +122,14 @@ static int check_playlist(struct osl_row *row, void *data)
        return 1;
 }
 
+/**
+ * Check the playlist table for inconsistencies.
+ *
+ * \param query Unused.
+ * \param result Contains messages about inconsistencies.
+ *
+ * \return The return value of the underlying call to osl_rbtree_loop().
+ */
 int playlist_check_callback(__a_unused const struct osl_object *query,
                struct osl_object *result)
 {
index 1f3922f..7b0db29 100644 (file)
@@ -1,3 +1,11 @@
+/*
+ * Copyright (C) 2007 Andre Noll <maan@systemlinux.org>
+ *
+ * Licensed under the GPL v2. For licencing details see COPYING.
+ */
+
+/** \file portable_io.h Inline functions for endian-independent binary IO. */
+
 static inline uint64_t read_portable(unsigned bits, const char *buf)
 {
        uint64_t ret = 0;
index 78d54f6..bf10783 100644 (file)
--- a/string.c
+++ b/string.c
@@ -393,7 +393,17 @@ __malloc char *para_hostname(void)
        return para_strdup(u.nodename);
 }
 
-enum for_each_line_modes{LINE_MODE_RO, LINE_MODE_RW};
+/**
+ * Used to distinguish between read-only and read-write mode.
+ *
+ * \sa for_each_line(), for_each_line_ro().
+ */
+enum for_each_line_modes{
+       /** Activate read-only mode. */
+       LINE_MODE_RO,
+       /** Activate read-write mode. */
+       LINE_MODE_RW
+};
 
 static int for_each_complete_line(enum for_each_line_modes mode, char *buf,
                size_t size, line_handler_t *line_handler, void *private_data)
@@ -446,12 +456,12 @@ static int for_each_complete_line(enum for_each_line_modes mode, char *buf,
 }
 
 /**
- * call a custom function for each complete line
+ * Call a custom function for each complete line.
  *
- * \param buf the buffer containing data seperated by newlines
- * \param size the number of bytes in \a buf
- * \param line_handler the custom function
- * \param private_data pointer to data which is passed to \a line_handler
+ * \param buf The buffer containing data seperated by newlines.
+ * \param size The number of bytes in \a buf.
+ * \param line_handler The custom function.
+ * \param private_data Pointer passed to \a line_handler.
  *
  * If \p line_handler is \p NULL, the function returns the number of complete
  * lines in \p buf.  Otherwise, \p line_handler is called for each complete
@@ -465,7 +475,7 @@ static int for_each_complete_line(enum for_each_line_modes mode, char *buf,
  * of bytes not handled to \p line_handler on success, or the negative return
  * value of the \p line_handler on errors.
  *
- * \sa for_each_line_ro()
+ * \sa for_each_line_ro().
  */
 int for_each_line(char *buf, size_t size, line_handler_t *line_handler,
                void *private_data)
@@ -475,21 +485,19 @@ int for_each_line(char *buf, size_t size, line_handler_t *line_handler,
 }
 
 /**
- * call a custom function for each complete line
- *
- * \param buf same meaning as in \p for_each_line
- * \param size same meaning as in \p for_each_line
- * \param line_handler same meaning as in \p for_each_line
- * \param private_data same meaning as in \p for_each_line
+ * Call a custom function for each complete line.
  *
- * This function behaves like \p for_each_line() with the following differences:
+ * \param buf Same meaning as in \p for_each_line().
+ * \param size Same meaning as in \p for_each_line().
+ * \param line_handler Same meaning as in \p for_each_line().
+ * \param private_data Same meaning as in \p for_each_line().
  *
- * - buf is left unchanged
+ * This function behaves like \p for_each_line(), but \a buf is left unchanged.
  *
  * \return On success, the function returns the number of complete lines in \p
  * buf, otherwise the (negative) return value of \p line_handler is returned.
  *
- * \sa for_each_line()
+ * \sa for_each_line().
  */
 int for_each_line_ro(char *buf, size_t size, line_handler_t *line_handler,
                void *private_data)
@@ -549,12 +557,14 @@ __printf_2_3 int para_printf(struct para_buffer *b, const char *fmt, ...)
        return ret;
 }
 
+/** \cond LLONG_MAX and LLONG_LIN might not be defined. */
 #ifndef LLONG_MAX
 #define LLONG_MAX (1 << (sizeof(long) - 1))
 #endif
 #ifndef LLONG_MIN
 #define LLONG_MIN (-LLONG_MAX - 1LL)
 #endif
+/** \endcond */
 
 /**
  * Convert a string to a 64-bit signed integer value.
index 16f4610..6759c26 100644 (file)
--- a/string.h
+++ b/string.h
@@ -6,9 +6,13 @@
 
 /** \file string.h exported sybmols from string.c */
 
+/** A string buffer used for para_printf(). */
 struct para_buffer {
+       /** The buffer. May be \p NULL. */
        char *buf;
+       /** The size of \a buf. */
        size_t size;
+       /** The next para_printf() will write at this offset. */
        size_t offset;
 };
 
@@ -29,6 +33,7 @@ __must_check unsigned split_args(char *args, char *** const argv_ptr, const char
 __malloc char *para_hostname(void);
 void valid_fd_012(void);
 __printf_2_3 int para_printf(struct para_buffer *b, const char *fmt, ...);
+/** Used for for_each_line() and for_each_line_ro(). */
 typedef int line_handler_t(char *, void *);
 int for_each_line(char *buf, size_t size, line_handler_t *line_handler,
        void *private_data);
diff --git a/write.c b/write.c
index a3b1de1..93c63c8 100644 (file)
--- a/write.c
+++ b/write.c
@@ -20,7 +20,9 @@
 #include "fd.h"
 #include "error.h"
 
+/** \cond */
 INIT_WRITE_ERRLISTS;
+/** \endcond */
 
 /**
  * check if given buffer contains a valid wave header