Doc enhancements.

README.md

@@ -27,9 +27,11 @@ minimal changes to the core. More documentation on the topic will follow.
 
 ## Development Status
 
-**Beta.** Considered feature-complete from an MVP standpoint. The API may
-change significantly. Most commits (not prefixed with "WIP") and merges to the
-master branch are pushed after tests pass with a clean `make memcheck` output.
+**Beta.** Considered feature-complete from an MVP standpoint. The API may still
+change significantly. Any API changes are marked by a new `v1.0b<n>` tag.  Most
+commits (not prefixed with "WIP") and merges to the master branch are pushed
+after tests pass with a clean `make memcheck` output (and on a good day, with a
+clean `doxygen`).
 
 Test coverage is not sufficient. Documentation is fairly extensive but needs
 reformatting. This code is being integrated in higher-level projects and is

include/volksdata/codec.h

@@ -3,7 +3,7 @@
 
 #include "volksdata/graph.h"
 
-/** @defgroup codec RDF codec module
+/** @defgroup codec_priv Private RDF codec API
  * @ingroup private
  * @{
  */
@@ -41,6 +41,115 @@ typedef struct parse_error_t {
 */
 
 
+/*
+ * Common utility functions.
+ */
+
+/** @brief strdup() for unsigned char.
+ *
+ * This is to be used with uint8_t sequences considered to be UTF-8 sequences,
+ * requird by re2c (it won't work with byte sequences containing `NUL`).
+ */
+inline uint8_t
+*uint8_dup (const uint8_t *str)
+{ return (uint8_t *) strdup ((char *) str); }
+
+
+/** @brief strndup() for unsigned char.
+ *
+ * This is to be used with uint8_t sequences considered to be UTF-8 sequences,
+ * requird by re2c (it won't work with byte sequences containing `NUL`).
+ */
+inline uint8_t
+*uint8_ndup (const uint8_t *str, size_t size)
+{ return (uint8_t *) strndup ((char *) str, size); }
+
+
+/** @brief Add escape character (backslash) to illegal literal characters.
+ *
+ * @param[in] in Input string.
+ *
+ * @param[out] out Output string.
+ *
+ * @return VOLK_OK on success; VOLK_MEM_ERR on memory error.
+ */
+VOLK_rc
+escape_lit (const char *in, char **out);
+
+
+/** @brief Replace non-printable characters with their literal byte.
+ *
+ *  Escape backslash is to be added separately.
+ */
+static inline char
+escape_char (const char c) {
+    switch (c) {
+        case '\t': return 't';
+        case '\b': return 'b';
+        case '\n': return 'n';
+        case '\r': return 'r';
+        case '\f': return 'f';
+        default: return c;
+    }
+}
+
+
+/** @brief Unescape a single character.
+ *
+ * Convert escaped special characters such as `\t`, `\n`, etc. into their
+ * corresponding code points.
+ *
+ * Non-special characters are returned unchanged.
+ *
+ * @param[in] c Character to unescape. Note that this is the single character
+ * after `\`.
+ * 
+ * @return Code point corresponding to the escaped character.
+ */
+inline char
+unescape_char (const char c)
+{
+    switch (c) {
+        case 't': return '\t';
+        case 'b': return '\b';
+        case 'n': return '\n';
+        case 'r': return '\r';
+        case 'f': return '\f';
+        default: return c;
+    }
+}
+
+
+/** @brief Replace `\uxxxx` and `\Uxxxxxxxx` with Unicode bytes.
+ *
+ * @param[in] esc_str Escaped string.
+ *
+ * @param[in] size Maximum number of characters to scan, à la strncpy().
+ *
+ * @return String with escape sequences replaced by Unicode bytes.
+ */
+uint8_t *unescape_unicode (const uint8_t *esc_str, size_t size);
+
+
+/** @brief Format an informational header.
+ *
+ * The information includes software version and current date. It is terminated
+ * by a newline + NUL and prefixed with the string specified in `pfx`. It is
+ * NOT prefixed by any comment characters.
+ *
+ * @param[in] pfx Prefix to add to the string. It may be a comment starter,
+ *  such as `# `.
+ */
+char *fmt_header (char *pfx);
+
+/// @}  END defgroup codec_priv
+
+
+/** @defgroup codec_p RDF encoder & decoder module
+ * @ingroup public
+ * @{
+ */
+
 /*
  * Interface prototypes.
  */
@@ -189,108 +298,6 @@ struct codec_t {
     term_decode_fn_t    decode_term;        ///< Term decoder function.
     gr_decode_fn_t      decode_graph;       ///< Graph decoder function.
 };
-
-
-/*
- * Common utility functions.
- */
-
-/** @brief strdup() for unsigned char.
- *
- * This is to be used with uint8_t sequences considered to be UTF-8 sequences,
- * requird by re2c (it won't work with byte sequences containing `NUL`).
- */
-inline uint8_t
-*uint8_dup (const uint8_t *str)
-{ return (uint8_t *) strdup ((char *) str); }
-
-
-/** @brief strndup() for unsigned char.
- *
- * This is to be used with uint8_t sequences considered to be UTF-8 sequences,
- * requird by re2c (it won't work with byte sequences containing `NUL`).
- */
-inline uint8_t
-*uint8_ndup (const uint8_t *str, size_t size)
-{ return (uint8_t *) strndup ((char *) str, size); }
-
-
-/** @brief Add escape character (backslash) to illegal literal characters.
- *
- * @param[in] in Input string.
- *
- * @param[out] out Output string.
- *
- * @return VOLK_OK on success; VOLK_MEM_ERR on memory error.
- */
-VOLK_rc
-escape_lit (const char *in, char **out);
-
-
-/** @brief Replace non-printable characters with their literal byte.
- *
- *  Escape backslash is to be added separately.
- */
-static inline char
-escape_char (const char c) {
-    switch (c) {
-        case '\t': return 't';
-        case '\b': return 'b';
-        case '\n': return 'n';
-        case '\r': return 'r';
-        case '\f': return 'f';
-        default: return c;
-    }
-}
-
-
-/** @brief Unescape a single character.
- *
- * Convert escaped special characters such as `\t`, `\n`, etc. into their
- * corresponding code points.
- *
- * Non-special characters are returned unchanged.
- *
- * @param[in] c Character to unescape. Note that this is the single character
- * after `\`.
- * 
- * @return Code point corresponding to the escaped character.
- */
-inline char
-unescape_char (const char c)
-{
-    switch (c) {
-        case 't': return '\t';
-        case 'b': return '\b';
-        case 'n': return '\n';
-        case 'r': return '\r';
-        case 'f': return '\f';
-        default: return c;
-    }
-}
-
-
-/** @brief Replace `\uxxxx` and `\Uxxxxxxxx` with Unicode bytes.
- *
- * @param[in] esc_str Escaped string.
- *
- * @param[in] size Maximum number of characters to scan, à la strncpy().
- *
- * @return String with escape sequences replaced by Unicode bytes.
- */
-uint8_t *unescape_unicode (const uint8_t *esc_str, size_t size);
-
-
-/** @brief Format an informational header.
- *
- * The information includes software version and current date. It is terminated
- * by a newline + NUL and prefixed with the string specified in `pfx`. It is
- * NOT prefixed by any comment characters.
- *
- * @param[in] pfx Prefix to add to the string. It may be a comment starter,
- *  such as `# `.
- */
-char *fmt_header (char *pfx);
-
 /// @}  END defgroup codec
+
 #endif

include/volksdata/core.h

@@ -44,7 +44,13 @@
 // TODO Cross-platform ramdisk path.
 #define TMPDIR "/tmp"
 
-/** @defgroup public LSUP Public API
+/** @defgroup public Public Volksdata API
+ * @{
+ */
+
+/**@defgroup const Constants
+ *
+ * @ingroup public
  * @{
  */
 #define VOLK_NS "urn:lsup:"             /// Default LS namespace.
@@ -59,6 +65,7 @@
 /** @brief "NULL" triple, a value that is never user-provided.
  */
 #define NULL_TRP {NULL_KEY, NULL_KEY, NULL_KEY}
+/// @} END defgroup const
 
 
 /* * * RETURN CODES * * */
@@ -235,7 +242,7 @@ VOLK_strerror (VOLK_rc rc);
 /// @} END defgroup public
 
 
-/** @defgroup private Private LSUP API
+/** @defgroup private Private Volksdata API
  * @{
  */
 /// minimum error value.
@@ -269,7 +276,7 @@ VOLK_strerror (VOLK_rc rc);
 #define LOG_RC(rc) do {                                             \
     if ((rc) < 0) log_error (VOLK_strerror (rc));                   \
     else if ((rc) > 0) log_warn (VOLK_strerror (rc));              \
-} while (0);
+} while (0)
 
 /// Jump to `marker` if `exp` does not return `VOLK_OK`.
 #define CHECK(exp, marker) do {                                     \
@@ -281,7 +288,7 @@ VOLK_strerror (VOLK_rc rc);
                 VOLK_strerror (_rc));                               \
         goto marker;                                                \
     }                                                               \
-} while (0);
+} while (0)
 
 /// Jump to `marker` if `exp` returns a negative value (skip warnings).
 #define PCHECK(exp, marker) do {                                    \
@@ -293,7 +300,7 @@ VOLK_strerror (VOLK_rc rc);
         LOG_RC(_rc);                                                \
         goto marker;                                                \
     }                                                               \
-} while (0);
+} while (0)
 
 /// Log error and jump to `marker` if `exp` is NULL.
 #define NLCHECK(exp, marker) do {                                   \
@@ -312,7 +319,7 @@ VOLK_strerror (VOLK_rc rc);
                 VOLK_strerror (_rc));                               \
         return _rc;                                                 \
     }                                                               \
-} while (0);
+} while (0)
 
 /// Return `exp` return value if it is of `VOLK_rc` type and negative (=error)
 #define PRCCK(exp) do {                                             \
@@ -323,7 +330,7 @@ VOLK_strerror (VOLK_rc rc);
                 VOLK_strerror (_rc));                               \
         return _rc;                                                 \
     }                                                               \
-} while (0);
+} while (0)
 
 /// Return `NULL` if `exp` returns a nonzero value.
 #define RCNL(exp) do {                                              \
@@ -345,7 +352,7 @@ VOLK_strerror (VOLK_rc rc);
                 VOLK_strerror (_rc));                               \
         return NULL;                                                \
     }                                                               \
-} while (0);
+} while (0)
 
 /// Log error and return NULL if `exp` is NULL.
 #define NLNL(exp) do {                                              \
@@ -353,19 +360,19 @@ VOLK_strerror (VOLK_rc rc);
         log_error ("*** PREMATURE EXIT due to NULL result.");       \
         return NULL;                                                \
     }                                                               \
-} while (0);
+} while (0)
 
 /// Allocate one pointer with malloc and return rc if it fails.
 #define MALLOC_GUARD(var, rc) do {                                  \
     (var) = malloc (sizeof *(var));                                 \
     if (UNLIKELY (var == NULL)) return (rc);                        \
-} while (0);
+} while (0)
 
 /// Allocate one pointer with calloc and return rc if it fails.
 #define CALLOC_GUARD(var, rc) do {                                  \
     (var) = calloc (1, sizeof *(var));                              \
     if (UNLIKELY (var == NULL)) return (rc);                        \
-} while (0);
+} while (0)
 
 /*
 #define MALLOC_GUARD_ME(var) MALLOC_GUARD((var), VOLK_MEM_ERR)      \

include/volksdata/store.h

@@ -122,6 +122,12 @@ void
 VOLK_store_free (VOLK_Store *store);
 
 
+/** @brief Store size in triples.
+ *
+ * @param[in] store Store handle.
+ *
+ * @return Number of triples in the store, across all contexts.
+ */
 size_t
 VOLK_store_size (const VOLK_Store *store);
 

src/codec/codec_ttl.c

@@ -6,7 +6,9 @@
  * This iterator yields one or more triples at a time, one group per subject,
  * with the most compact form allowed by Turtle, e.g.
  *
- * ```:s :p1 :o1, :o2, o3; :p2 :o4, :o5, <http://example.com/ext1> .```
+ * ```
+ * :s :p1 :o1, :o2, o3; :p2 :o4, :o5, <http://example.com/ext1> .
+ * ```
  */
 typedef struct {
     const VOLK_Codec *  codec;      ///< Codec that generated this iterator.