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 25aa2a6dc323ed99efba3a78d247c25b27205da1..2d3aea1e7234b47a22636fcbf630fc115d5bcc42 100644 (file)
--- 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 4696ee4a118c5791cfa40ae5cef2c4eb634807ef..833bbf1b87e5d8a34fff91d4558820ee33191d27 100644 (file)
--- 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 306546d6c89bfdd2ee80832ed4c71b655bdf7b05..65494131ba518827dc3df6c228ca8d776a01fa71 100644 (file)
--- 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 b0d44ec991cb49568eb20b4a4106928ae5363f4e..d72d85e7fb3720d67feab92fc140d4f01acdde4e 100644 (file)
--- 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 5dc3912409b5dd64c71a0d68e2fcbbde2cfe466a..bc6aa929539ee4a9c1abb8e0d2b14695d88870cc 100644 (file)
--- 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 ee8138f9d9c12a9674600091d3073b1807dc41ba..7555dfb4130010898145bb6bb89b679a5e69e78a 100644 (file)
--- 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 0a32c0f48b3b8fc9a1b5194587fc10068789a064..cefb45d674075cf1fcb2e42b42e5b0a929a52c16 100644 (file)
--- 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 3ec2a2d437422f39e9845b7f519e01ae4216b89c..d7d803d932efd704642f9098989f6661f2731377 100644 (file)
--- 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,