From: Andre Noll Date: Sat, 1 Oct 2011 21:35:18 +0000 (+0200) Subject: doc: Minor doxygen fixes. X-Git-Tag: v0.4.9~22 X-Git-Url: http://git.tuebingen.mpg.de/?p=paraslash.git;a=commitdiff_plain;h=4ad9b98ca90d603eecb5c9c403e0f7bbdc3be6a6 doc: Minor doxygen fixes. doxygen's \cond and \endcond commands treat the word after the command as the name of the section which should be excluded from the documentatation. So it is wrong to put an arbitrary comment there. This fixes a couple of doxygen warnings about unknown loglevel defines and makes these defines actually show up in the generated HTML. --- diff --git a/blob.c b/blob.c index 25aa2a6d..2d3aea1e 100644 --- a/blob.c +++ b/blob.c @@ -80,12 +80,13 @@ static struct osl_column_description blob_cols[] = { DEFINE_BLOB_TABLE_DESC(table_name); \ DEFINE_BLOB_TABLE_PTR(table_name); -/** \cond doxygen isn't smart enough to recognize these */ +/* doxygen isn't smart enough to recognize these */ +/** \cond blob_table */ INIT_BLOB_TABLE(lyrics); INIT_BLOB_TABLE(images); INIT_BLOB_TABLE(moods); INIT_BLOB_TABLE(playlists); -/** \endcond */ +/** \endcond blob_table */ /** Flags that may be passed to the \p ls functions of each blob type. */ enum blob_ls_flags { @@ -662,9 +663,10 @@ static int blob_open(struct osl_table **table, DEFINE_GET_DEF_BY_NAME(table_name, cmd_prefix); \ DEFINE_GET_NAME_AND_DEF_BY_ROW(table_name, cmd_prefix); \ -/** \cond doxygen isn't smart enough to recognize these */ +/* doxygen isn't smart enough to recognize these */ +/** \cond blob_function */ DEFINE_BLOB_FUNCTIONS(lyrics, lyr); DEFINE_BLOB_FUNCTIONS(images, img); DEFINE_BLOB_FUNCTIONS(moods, mood); DEFINE_BLOB_FUNCTIONS(playlists, pl); -/** \endcond */ +/** \endcond blob_function */ diff --git a/crypt.h b/crypt.h index 4696ee4a..833bbf1b 100644 --- a/crypt.h +++ b/crypt.h @@ -7,13 +7,14 @@ /** \file crypt.h Public crypto interface. */ -/** \cond used to distinguish between loading of private/public key */ +/* These are used to distinguish between loading of private/public key. */ + +/** The key to load is a public key. */ #define LOAD_PUBLIC_KEY 0 +/** The key to load is a private key. */ #define LOAD_PRIVATE_KEY 1 +/** The size of the challenge sent to the client. */ #define CHALLENGE_SIZE 64 -/** \endcond **/ - -/* asymetric (public key) crypto */ /** Opaque structure for public and private keys. */ struct asymmetric_key; diff --git a/error.h b/error.h index 306546d6..65494131 100644 --- a/error.h +++ b/error.h @@ -6,7 +6,7 @@ /** \file error.h List of error messages for all subsystems. */ -/** \cond */ +/** \cond errors */ /* List of all subsystems that use paraslash's error facility. */ DEFINE_ERRLIST_OBJECT_ENUM; @@ -455,7 +455,7 @@ extern const char **para_errlist[]; PARA_ERROR(QUEUE, "packet queue overrun"), \ -/** \endcond */ +/** \endcond errors */ /** * The subsystem shift. diff --git a/mp3_afh.c b/mp3_afh.c index b0d44ec9..d72d85e7 100644 --- a/mp3_afh.c +++ b/mp3_afh.c @@ -23,8 +23,6 @@ #include "afh.h" #include "string.h" -/** \cond some defines and structs which are only used in this file */ - /* * MIN_CONSEC_GOOD_FRAMES defines how many consecutive valid MP3 frames we need * to see before we decide we are looking at a real MP3 file @@ -47,7 +45,6 @@ struct mp3header { unsigned int emphasis; }; -/** \endcond */ static const int frequencies[3][4] = { {22050,24000,16000,50000}, /* MPEG 2.0 */ {44100,48000,32000,50000}, /* MPEG 1.0 */ diff --git a/para.h b/para.h index 5dc39124..bc6aa929 100644 --- a/para.h +++ b/para.h @@ -229,12 +229,12 @@ _static_inline_ long int para_random(unsigned max) SAMPLE_FORMAT(SF_U16_LE, "16 bit unsigned, little endian"), \ SAMPLE_FORMAT(SF_U16_BE, "16 bit unsigned, big endian"), \ -/** \cond */ +/** \cond sample_format */ #define SAMPLE_FORMAT(a, b) a enum sample_format {SAMPLE_FORMATS}; #undef SAMPLE_FORMAT #define SAMPLE_FORMAT(a, b) b -/** \endcond */ +/** \endcond sample_format */ /** Debug loglevel, gets really noisy. */ #define LL_DEBUG 0 @@ -256,7 +256,7 @@ enum sample_format {SAMPLE_FORMATS}; /** Log messages with lower priority than that will not be compiled in. */ #define COMPILE_TIME_LOGLEVEL 0 -/** \cond */ +/** \cond log */ #if LL_DEBUG >= COMPILE_TIME_LOGLEVEL #define PARA_DEBUG_LOG(f,...) para_log(LL_DEBUG, "%s: " f, __FUNCTION__, ## __VA_ARGS__) #else @@ -298,4 +298,4 @@ enum sample_format {SAMPLE_FORMATS}; #else #define PARA_EMERG_LOG(...) #endif -/** \endcond */ +/** \endcond log */ diff --git a/recv.h b/recv.h index ee8138f9..7555dfb4 100644 --- a/recv.h +++ b/recv.h @@ -121,7 +121,7 @@ void *check_receiver_arg(char *ra, int *receiver_num); void print_receiver_helps(int detailed); int generic_recv_pre_select(struct sched *s, struct task *t); -/** \cond */ +/** \cond receiver */ extern void http_recv_init(struct receiver *r); #define HTTP_RECEIVER {.name = "http", .init = http_recv_init}, extern void dccp_recv_init(struct receiver *r); @@ -130,5 +130,5 @@ extern void udp_recv_init(struct receiver *r); #define UDP_RECEIVER {.name = "udp", .init = udp_recv_init}, extern struct receiver receivers[]; -/** \endcond */ +/** \endcond receiver */ diff --git a/string.c b/string.c index 0a32c0f4..cefb45d6 100644 --- a/string.c +++ b/string.c @@ -521,14 +521,15 @@ __printf_2_3 int para_printf(struct para_buffer *b, const char *fmt, ...) } } -/** \cond LLONG_MAX and LLONG_MIN might not be defined. */ +/** \cond llong_minmax */ +/* LLONG_MAX and LLONG_MIN might not be defined. */ #ifndef LLONG_MAX #define LLONG_MAX 9223372036854775807LL #endif #ifndef LLONG_MIN #define LLONG_MIN (-LLONG_MAX - 1LL) #endif -/** \endcond */ +/** \endcond llong_minmax */ /** * Convert a string to a 64-bit signed integer value. diff --git a/time.c b/time.c index 3ec2a2d4..d7d803d9 100644 --- a/time.c +++ b/time.c @@ -82,7 +82,7 @@ int tv_diff(const struct timeval *b, const struct timeval *a, struct timeval *di * * \param a First addend. * \param b Second addend. - * \param sum Contains the sum \a + \a b on return. + * \param sum Contains the sum \a a + \a b on return. */ void tv_add(const struct timeval *a, const struct timeval *b, struct timeval *sum) @@ -180,7 +180,7 @@ int tv_convex_combination(const long a, const struct timeval *tv1, * \param stream_start When the first chunk was sent. * \param result The time when to send chunk number \a chunk_num. * - * This function computes stream_start + chunk_num * chunk_time. + * This function computes \a stream_start + \a chunk_num * \a chunk_time. */ void compute_chunk_time(long unsigned chunk_num, struct timeval *chunk_tv, struct timeval *stream_start,