From: Andre Noll Date: Sat, 6 Oct 2007 17:00:24 +0000 (+0200) Subject: Add more documentation. X-Git-Tag: v0.3.0~298 X-Git-Url: http://git.tuebingen.mpg.de/?p=paraslash.git;a=commitdiff_plain;h=ea689d919fd6fdbfaba2de9d1cd207e033c319fd Add more documentation. --- diff --git a/afs.c b/afs.c index de713fa7..a3b8d883 100644 --- 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 7167da49..ab2db3aa 100644 --- 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 #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 431bedb6..c6ca289f 100644 --- 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. * diff --git a/attribute.c b/attribute.c index 671ca056..d34f7d63 100644 --- a/attribute.c +++ b/attribute.c @@ -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 99f4486a..51028c4e 100644 --- a/hash.h +++ b/hash.h @@ -1,12 +1,30 @@ +/* + * Copyright (C) 2007 Andre Noll + * + * 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 0e41be1c..9a935539 100644 --- 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 5dec070f..dea92910 100644 --- a/para.h +++ b/para.h @@ -52,9 +52,10 @@ /** 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))); diff --git a/playlist.c b/playlist.c index 6f9f9669..ba99fad2 100644 --- a/playlist.c +++ b/playlist.c @@ -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) { diff --git a/portable_io.h b/portable_io.h index 1f3922f8..7b0db29b 100644 --- a/portable_io.h +++ b/portable_io.h @@ -1,3 +1,11 @@ +/* + * Copyright (C) 2007 Andre Noll + * + * 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; diff --git a/string.c b/string.c index 78d54f67..bf107834 100644 --- 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. diff --git a/string.h b/string.h index 16f46108..6759c261 100644 --- 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 a3b1de1c..93c63c8d 100644 --- 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