chiark / gitweb /
More doc comments
authorRichard Kettlewell <rjk@greenend.org.uk>
Sun, 8 Nov 2009 13:36:13 +0000 (13:36 +0000)
committerRichard Kettlewell <rjk@greenend.org.uk>
Sun, 8 Nov 2009 13:36:13 +0000 (13:36 +0000)
lib/fprintf.c
lib/hash.h
lib/kvp.c
lib/log.h
lib/logfd.c
lib/printf.c

index b4de830..ac0c0d8 100644 (file)
 #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;
index e932f4b..f0efa54 100644 (file)
 #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;
 
index 5a116de..45aa03c 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;
 }
 
+/** @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;
index 5d39732..ecabd30 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;
 
+/** @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__;                   \
index a6f14c3..015321a 100644 (file)
@@ -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) {
index f921791..15cd8ad 100644 (file)
 #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.