doc: Minor doxygen fixes.
authorAndre Noll <maan@systemlinux.org>
Sat, 1 Oct 2011 21:35:18 +0000 (23:35 +0200)
committerAndre Noll <maan@systemlinux.org>
Sat, 1 Oct 2011 21:35:18 +0000 (23:35 +0200)
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.

blob.c
crypt.h
error.h
mp3_afh.c
para.h
recv.h
string.c
time.c

diff --git a/blob.c b/blob.c
index 25aa2a6..2d3aea1 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 4696ee4..833bbf1 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 306546d..6549413 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.
index b0d44ec..d72d85e 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 5dc3912..bc6aa92 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 ee8138f..7555dfb 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 */
 
index 0a32c0f..cefb45d 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 3ec2a2d..d7d803d 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 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,