From 006827074fe1dc0b85de76982e1b9bf5cda07e34 Mon Sep 17 00:00:00 2001
Message-Id: <006827074fe1dc0b85de76982e1b9bf5cda07e34.1715601038.git.mdw@distorted.org.uk>
From: Mark Wooding <mdw@chiark.greenend.org.uk>
Date: Sun, 8 Nov 2009 13:36:13 +0000
Subject: [PATCH] More doc comments
Organization: Straylight/Edgeware

From: Richard Kettlewell <rjk@greenend.org.uk>

---
 lib/fprintf.c | 12 ++++++++++++
 lib/hash.h    |  4 ++++
 lib/kvp.c     |  5 +++++
 lib/log.h     |  5 +++++
 lib/logfd.c   |  4 ++--
 lib/printf.c  | 41 +++++++++++++++++++++++++++++++++++++++++
 6 files changed, 69 insertions(+), 2 deletions(-)

diff --git a/lib/fprintf.c b/lib/fprintf.c
index b4de830..ac0c0d8 100644
--- a/lib/fprintf.c
+++ b/lib/fprintf.c
@@ -27,10 +27,22 @@
 #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);
 }
 
+/** @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;
diff --git a/lib/hash.h b/lib/hash.h
index e932f4b..f0efa54 100644
--- a/lib/hash.h
+++ b/lib/hash.h
@@ -22,6 +22,10 @@
 #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;
 
diff --git a/lib/kvp.c b/lib/kvp.c
index 5a116de..45aa03c 100644
--- 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;
 }
 
+/** @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;
diff --git a/lib/log.h b/lib/log.h
index 5d39732..ecabd30 100644
--- a/lib/log.h
+++ b/lib/log.h
@@ -69,6 +69,11 @@ extern const char *debug_filename;
 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__;			\
diff --git a/lib/logfd.c b/lib/logfd.c
index a6f14c3..015321a 100644
--- a/lib/logfd.c
+++ b/lib/logfd.c
@@ -29,7 +29,7 @@
 #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,
@@ -54,7 +54,7 @@ static int logfd_readable(ev_source attribute((unused)) *ev,
   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) {
diff --git a/lib/printf.c b/lib/printf.c
index f921791..15cd8ad 100644
--- a/lib/printf.c
+++ b/lib/printf.c
@@ -32,6 +32,10 @@
 #include "sink.h"
 #include "vacopy.h"
 
+/** @brief Flags from a converstion specification
+ *
+ * Order significant!
+ */
 enum flags {
   f_thousands = 1,
   f_left = 2,
@@ -43,6 +47,7 @@ enum flags {
   f_precision = 512
 };
 
+/** @brief Possible lengths of a conversion specification */
 enum lengths {
   l_char = 1,
   l_short,
@@ -56,29 +61,65 @@ enum lengths {
 
 struct conversion;
 
+/** @brief Formatter state */
 struct state {
+  /** @brief Output stream */
   struct sink *output;
+
+  /** @brief Number of bytes written */
   int bytes;
+
+  /** @brief Argument list */
   va_list ap;
 };
 
+/** @brief Definition of a conversion specifier */
 struct specifier {
+  /** @brief Defining character ('d', 's' etc) */
   int ch;
+
+  /** @brief Consistency check
+   * @param c Conversion being processed
+   * @return 0 if OK, -1 on error
+   */
   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);
+
+  /** @brief Number base */
   int base;
+
+  /** @brief Digit set */
   const char *digits;
+
+  /** @brief Alternative-form prefix */
   const char *xform;
 };
 
+/** @brief One conversion specified as it's handled */
 struct conversion {
+  /** @brief Flags in this conversion */
   unsigned flags;
+
+  /** @brief Field width (if @ref f_width) */
   int width;
+
+  /** @brief Precision (if @ref f_precision) */
   int precision;
+
+  /** @brief Length modifier or 0 */
   int length;
+
+  /** @brief Specifier used */
   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.
-- 
[mdw]