More doc comments

diff --git a/lib/fprintf.c b/lib/fprintf.c
index b4de8300cd8175706198245c986523e70641862b..ac0c0d813f8e070acc2df1e258403234ea53df9b 100644 (file)
--- a/lib/fprintf.c
+++ b/lib/fprintf.c
@@ -27,10 +27,22 @@
 #include "printf.h"
 #include "sink.h"
 
 #include "printf.h"
 #include "sink.h"
 

+/** @brief vfprintf() workalike that always accepts UTF-8
+ * @param fp Stream to write to
+ * @param fmt Format string
+ * @param ap Format arguments
+ * @return -1 on error or bytes written on success
+ */

 int byte_vfprintf(FILE *fp, const char *fmt, va_list ap) {
   return byte_vsinkprintf(sink_stdio(0, fp), fmt, ap);
 }
 
 int byte_vfprintf(FILE *fp, const char *fmt, va_list ap) {
   return byte_vsinkprintf(sink_stdio(0, fp), fmt, ap);
 }
 

+/** @brief fprintf() workalike that always accepts UTF-8
+ * @param fp Stream to write to
+ * @param fmt Format string
+ * @param ... Format arguments
+ * @return -1 on error or bytes written on success
+ */

 int byte_fprintf(FILE *fp, const char *fmt, ...) {
   int n;
   va_list ap;
 int byte_fprintf(FILE *fp, const char *fmt, ...) {
   int n;
   va_list ap;

diff --git a/lib/hash.h b/lib/hash.h
index e932f4b359b93534b0dd08a2ee05757be5ab140a..f0efa54b4a8be345cd57f3769df3def27e8ce94b 100644 (file)
--- a/lib/hash.h
+++ b/lib/hash.h
@@ -22,6 +22,10 @@
 #ifndef HASH_H
 #define HASH_H
 
 #ifndef HASH_H
 #define HASH_H
 

+/** @brief Hash structure
+ *
+ * A hash table has string keys and byte blocks of fixed size as values.
+ */

 typedef struct hash hash;
 struct kvp;
 
 typedef struct hash hash;
 struct kvp;
 

diff --git a/lib/kvp.c b/lib/kvp.c
index 5a116deab632720b1c31c31d1ac4dc495961d457..45aa03c190f3533540b95f323d473e9e95b0b594 100644 (file)
--- a/lib/kvp.c
+++ b/lib/kvp.c
@@ -63,6 +63,11 @@ int urldecode(struct sink *sink, const char *ptr, size_t n) {
   return 0;
 }
 
   return 0;
 }
 

+/** @brief URL-decode a string
+ * @param ptr Start of URL-encoded string
+ * @param n Length of @p ptr
+ * @return Decoded string (0-terminated)
+ */

 static char *decode(const char *ptr, size_t n) {
   struct dynstr d;
   struct sink *s;
 static char *decode(const char *ptr, size_t n) {
   struct dynstr d;
   struct sink *s;

diff --git a/lib/log.h b/lib/log.h
index 5d39732d7f2996adadd6b4a395af7f22fc837191..ecabd30f8a7ffd9779ad6a16f6ab5d4392aab743 100644 (file)
--- a/lib/log.h
+++ b/lib/log.h
@@ -69,6 +69,11 @@ extern const char *debug_filename;
 extern int debug_lineno;
 extern int logdate;
 
 extern int debug_lineno;
 extern int logdate;
 

+/** @brief Issue a debug message if debugging is turned on
+ * @param x Parenthesized debug arguments
+ *
+ * Use in the format: D(("format string", arg, arg, ...));
+ */

 #define D(x) do {                              \
   if(debugging) {                              \
     debug_filename=__FILE__;                   \
 #define D(x) do {                              \
   if(debugging) {                              \
     debug_filename=__FILE__;                   \

diff --git a/lib/logfd.c b/lib/logfd.c
index a6f14c3022a44766c350158340967ef027a06548..015321a3de93da0acfb5433bf532afff4cc5d3f3 100644 (file)
--- a/lib/logfd.c
+++ b/lib/logfd.c
@@ -29,7 +29,7 @@
 #include "event.h"
 #include "log.h"
 
 #include "event.h"
 #include "log.h"
 

-/* called when bytes are available and at eof */
+/** @brief Called when a log FD is readable */

 static int logfd_readable(ev_source attribute((unused)) *ev,
                          ev_reader *reader,
                          void *ptr,
 static int logfd_readable(ev_source attribute((unused)) *ev,
                          ev_reader *reader,
                          void *ptr,


@@ -54,7 +54,7 @@ static int logfd_readable(ev_source attribute((unused)) *ev,
   return 0;
 }
 
   return 0;
 }
 

-/* called when a read error occurs */
+/** @brief Called when a log FD errors */

 static int logfd_error(ev_source attribute((unused)) *ev,
                       int errno_value,
                       void *u) {
 static int logfd_error(ev_source attribute((unused)) *ev,
                       int errno_value,
                       void *u) {

diff --git a/lib/printf.c b/lib/printf.c
index f921791ed32961b6c12959a1e070e1a30d44fd0e..15cd8ad968463f4201913b87c7787acbedf44d91 100644 (file)
--- a/lib/printf.c
+++ b/lib/printf.c
@@ -32,6 +32,10 @@
 #include "sink.h"
 #include "vacopy.h"
 
 #include "sink.h"
 #include "vacopy.h"
 

+/** @brief Flags from a converstion specification
+ *
+ * Order significant!
+ */

 enum flags {
   f_thousands = 1,
   f_left = 2,
 enum flags {
   f_thousands = 1,
   f_left = 2,


@@ -43,6 +47,7 @@ enum flags {
   f_precision = 512
 };
 
   f_precision = 512
 };
 

+/** @brief Possible lengths of a conversion specification */

 enum lengths {
   l_char = 1,
   l_short,
 enum lengths {
   l_char = 1,
   l_short,


@@ -56,29 +61,65 @@ enum lengths {
 
 struct conversion;
 
 
 struct conversion;
 

+/** @brief Formatter state */

 struct state {
 struct state {

+  /** @brief Output stream */

   struct sink *output;
   struct sink *output;

+
+  /** @brief Number of bytes written */

   int bytes;
   int bytes;

+
+  /** @brief Argument list */

   va_list ap;
 };
 
   va_list ap;
 };
 

+/** @brief Definition of a conversion specifier */

 struct specifier {
 struct specifier {

+  /** @brief Defining character ('d', 's' etc) */

   int ch;
   int ch;

+
+  /** @brief Consistency check
+   * @param c Conversion being processed
+   * @return 0 if OK, -1 on error
+   */

   int (*check)(const struct conversion *c);
   int (*check)(const struct conversion *c);

+
+  /** @brief Generate output
+   * @param s Formatter state
+   * @param c Conversion being processed
+   * @return 0 on success, -1 on error
+   */

   int (*output)(struct state *s, struct conversion *c);
   int (*output)(struct state *s, struct conversion *c);

+
+  /** @brief Number base */

   int base;
   int base;

+
+  /** @brief Digit set */

   const char *digits;
   const char *digits;

+
+  /** @brief Alternative-form prefix */

   const char *xform;
 };
 
   const char *xform;
 };
 

+/** @brief One conversion specified as it's handled */

 struct conversion {
 struct conversion {

+  /** @brief Flags in this conversion */

   unsigned flags;
   unsigned flags;

+
+  /** @brief Field width (if @ref f_width) */

   int width;
   int width;

+
+  /** @brief Precision (if @ref f_precision) */

   int precision;
   int precision;

+
+  /** @brief Length modifier or 0 */

   int length;
   int length;

+
+  /** @brief Specifier used */

   const struct specifier *specifier;
 };
 
   const struct specifier *specifier;
 };
 

+/** @brief Flag characters (order significant!) */

 static const char flags[] = "'-+ #0";
 
 /* write @nbytes@ to the output.  Return -1 on error, 0 on success.
 static const char flags[] = "'-+ #0";
 
 /* write @nbytes@ to the output.  Return -1 on error, 0 on success.