Use line comments where appropriate and clean up header

1 files changed, 211 insertions, 437 deletions

diff --git a/serd/serd.h b/serd/serd.h
index f18968e7..9c20dc0f 100644
--- a/serd/serd.h
+++ b/serd/serd.h
@@ -14,9 +14,7 @@
   OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
 */
 
-/**
-   @file serd.h API for Serd, a lightweight RDF syntax library.
-*/
+/// @file serd.h API for Serd, a lightweight RDF syntax library
 
 #ifndef SERD_SERD_H
 #define SERD_SERD_H
@@ -50,136 +48,73 @@ extern "C" {
 
 /**
    @defgroup serd Serd
-   A lightweight RDF syntax library.
+   A lightweight RDF syntax library
    @{
 */
 
-/**
-   World.
-
-   The World represents all library state shared between various objects.
-*/
+/// Global library state
 typedef struct SerdWorldImpl SerdWorld;
 
-/**
-   Nodes.
-
-   A hashing container for nodes that can be used for interning and simplified
-   memory management.
-*/
+/// Hashing node container for interning and simplified memory management
 typedef struct SerdNodesImpl SerdNodes;
 
-/**
-   Statement.
-
-   A subject, predicate, and object, with optional graph context.
-*/
+/// A subject, predicate, and object, with optional graph context
 typedef struct SerdStatementImpl SerdStatement;
 
-/**
-   Cursor, the origin of a statement in a document.
-*/
+/// The origin of a statement in a document
 typedef struct SerdCursorImpl SerdCursor;
 
-/**
-   Environment.
-
-   Represents the state required to resolve a CURIE or relative URI, e.g. the
-   base URI and set of namespace prefixes at a particular point.
-*/
+/// Lexical environment for relative URIs or CURIEs (base URI and namespaces)
 typedef struct SerdEnvImpl SerdEnv;
 
-/**
-   RDF reader.
-
-   Parses RDF by calling user-provided sink functions as input is consumed
-   (much like an XML SAX parser).
-*/
+/// Streaming parser that reads a text stream and writes to a statement sink
 typedef struct SerdReaderImpl SerdReader;
 
-/**
-   RDF writer.
-
-   Provides a number of functions to allow writing RDF syntax out to some
-   stream.  These functions are deliberately compatible with the sink functions
-   used by SerdReader, so a reader can be directly connected to a writer to
-   re-serialise a document with minimal overhead.
-*/
+/// Streaming serialiser that writes a text stream as statements are pushed
 typedef struct SerdWriterImpl SerdWriter;
 
-/**
-   An interface that receives a stream of RDF data.
-*/
+/// An interface that receives a stream of RDF data
 typedef struct SerdSinkImpl SerdSink;
 
-/**
-   A sink for bytes that receives string output.
-*/
+/// A sink for bytes that receives string output
 typedef struct SerdByteSinkImpl SerdByteSink;
 
-/**
-   Return status code.
-*/
+/// Return status code
 typedef enum {
-	SERD_SUCCESS,         /**< No error */
-	SERD_FAILURE,         /**< Non-fatal failure */
-	SERD_ERR_UNKNOWN,     /**< Unknown error */
-	SERD_ERR_BAD_SYNTAX,  /**< Invalid syntax */
-	SERD_ERR_BAD_ARG,     /**< Invalid argument */
-	SERD_ERR_NOT_FOUND,   /**< Not found */
-	SERD_ERR_ID_CLASH,    /**< Encountered clashing blank node IDs */
-	SERD_ERR_BAD_CURIE,   /**< Invalid CURIE (e.g. prefix does not exist) */
-	SERD_ERR_INTERNAL,    /**< Unexpected internal error (should not happen) */
-	SERD_ERR_OVERFLOW     /**< Stack overflow */
+	SERD_SUCCESS,         ///< No error
+	SERD_FAILURE,         ///< Non-fatal failure
+	SERD_ERR_UNKNOWN,     ///< Unknown error
+	SERD_ERR_BAD_SYNTAX,  ///< Invalid syntax
+	SERD_ERR_BAD_ARG,     ///< Invalid argument
+	SERD_ERR_NOT_FOUND,   ///< Not found
+	SERD_ERR_ID_CLASH,    ///< Encountered clashing blank node IDs
+	SERD_ERR_BAD_CURIE,   ///< Invalid CURIE (e.g. prefix does not exist)
+	SERD_ERR_INTERNAL,    ///< Unexpected internal error (should not happen)
+	SERD_ERR_OVERFLOW     ///< Stack overflow
 } SerdStatus;
 
-/**
-   RDF syntax type.
-*/
+/// RDF syntax type
 typedef enum {
-	/**
-	   Turtle - Terse RDF Triple Language (UTF-8).
-	   @see <a href="http://www.w3.org/TeamSubmission/turtle/">Turtle</a>
-	*/
-	SERD_TURTLE = 1,
-
-	/**
-	   NTriples - Line-based RDF triples (ASCII).
-	   @see <a href="http://www.w3.org/TR/rdf-testcases#ntriples">NTriples</a>
-	*/
-	SERD_NTRIPLES = 2,
-
-	/**
-	   NQuads - Line-based RDF quads (UTF-8).
-	   @see <a href="https://www.w3.org/TR/n-quads/">NQuads</a>
-	*/
-	SERD_NQUADS = 3,
-
-	/**
-	   TriG - Terse RDF quads (UTF-8).
-	   @see <a href="https://www.w3.org/TR/trig/">Trig</a>
-	*/
-	SERD_TRIG = 4
+	SERD_TURTLE   = 1,  ///< Terse triples http://www.w3.org/TR/turtle
+	SERD_NTRIPLES = 2,  ///< Line-based triples http://www.w3.org/TR/n-triples/
+	SERD_NQUADS   = 3,  ///< Line-based quads http://www.w3.org/TR/n-quads/
+	SERD_TRIG     = 4   ///< Terse quads http://www.w3.org/TR/trig/
 } SerdSyntax;
 
-/**
-   Flags indicating inline abbreviation information for a statement.
-*/
+/// Flags indicating inline abbreviation information for a statement
 typedef enum {
-	SERD_EMPTY_S = 1 << 0,  /**< Empty blank node subject */
-	SERD_ANON_S  = 1 << 1,  /**< Start of anonymous subject */
-	SERD_ANON_O  = 1 << 2,  /**< Start of anonymous object */
-	SERD_LIST_S  = 1 << 3,  /**< Start of list subject */
-	SERD_LIST_O  = 1 << 4   /**< Start of list object */
+	SERD_EMPTY_S = 1 << 0,  ///< Empty blank node subject
+	SERD_ANON_S  = 1 << 1,  ///< Start of anonymous subject
+	SERD_ANON_O  = 1 << 2,  ///< Start of anonymous object
+	SERD_LIST_S  = 1 << 3,  ///< Start of list subject
+	SERD_LIST_O  = 1 << 4   ///< Start of list object
 } SerdStatementFlag;
 
-/**
-   Bitwise OR of SerdStatementFlag values.
-*/
+/// Bitwise OR of SerdStatementFlag values
 typedef uint32_t SerdStatementFlags;
 
 /**
-   Type of a syntactic RDF node.
+   Type of a syntactic RDF node
 
    This is more precise than the type of an abstract RDF node.  An abstract
    node is either a resource, literal, or blank.  In syntax there are two ways
@@ -189,91 +124,75 @@ typedef uint32_t SerdStatementFlags;
 */
 typedef enum {
 	/**
-	   Literal value.
+	   Literal value
 
 	   A literal optionally has either a language, or a datatype (not both).
 	*/
 	SERD_LITERAL = 1,
 
 	/**
-	   URI (absolute or relative).
+	   URI (absolute or relative)
 
 	   Value is an unquoted URI string, which is either a relative reference
 	   with respect to the current base URI (e.g. "foo/bar"), or an absolute
 	   URI (e.g. "http://example.org/foo").
-	   @see <a href="http://tools.ietf.org/html/rfc3986">RFC3986</a>.
+	   @see [RFC3986](http://tools.ietf.org/html/rfc3986)
 	*/
 	SERD_URI = 2,
 
 	/**
-	   CURIE, a shortened URI.
+	   CURIE, a shortened URI
 
 	   Value is an unquoted CURIE string relative to the current environment,
-	   e.g. "rdf:type".
-	   @see <a href="http://www.w3.org/TR/curie">CURIE Syntax 1.0</a>
+	   e.g. "rdf:type".  @see [CURIE Syntax 1.0](http://www.w3.org/TR/curie)
 	*/
 	SERD_CURIE = 3,
 
 	/**
-	   A blank node.
+	   A blank node
 
-	   Value is a blank node ID, e.g. "id3", which is meaningful only within
-	   this serialisation.
-	   @see <a href="http://www.w3.org/TeamSubmission/turtle#nodeID">Turtle
-	   <tt>nodeID</tt></a>
+	   Value is a blank node ID without any syntactic prefix, like "id3", which
+	   is meaningful only within this serialisation.  @see [RDF 1.1
+	   Turtle](http://www.w3.org/TR/turtle/#grammar-production-BLANK_NODE_LABEL)
 	*/
 	SERD_BLANK = 4
 } SerdNodeType;
 
-/**
-   Flags indicating certain string properties relevant to serialisation.
-*/
+/// Flags indicating certain string properties relevant to serialisation
 typedef enum {
-	SERD_HAS_NEWLINE  = 1,      /**< Contains line breaks ('\\n' or '\\r') */
-	SERD_HAS_QUOTE    = 1 << 1, /**< Contains quotes ('"') */
-	SERD_HAS_DATATYPE = 1 << 2, /**< Literal node has datatype */
-	SERD_HAS_LANGUAGE = 1 << 3  /**< Literal node has language */
+	SERD_HAS_NEWLINE  = 1,      ///< Contains line breaks ('\\n' or '\\r')
+	SERD_HAS_QUOTE    = 1 << 1, ///< Contains quotes ('"')
+	SERD_HAS_DATATYPE = 1 << 2, ///< Literal node has datatype
+	SERD_HAS_LANGUAGE = 1 << 3  ///< Literal node has language
 } SerdNodeFlag;
 
-/**
-   Field in a statement.
-*/
+/// Bitwise OR of SerdNodeFlag values
+typedef uint32_t SerdNodeFlags;
+
+/// Field in a statement
 typedef enum {
-	SERD_SUBJECT   = 0,  /**< Subject */
-	SERD_PREDICATE = 1,  /**< Predicate ("key") */
-	SERD_OBJECT    = 2,  /**< Object    ("value") */
-	SERD_GRAPH     = 3   /**< Graph     ("context") */
+	SERD_SUBJECT   = 0,  ///< Subject
+	SERD_PREDICATE = 1,  ///< Predicate ("key")
+	SERD_OBJECT    = 2,  ///< Object    ("value")
+	SERD_GRAPH     = 3   ///< Graph     ("context")
 } SerdField;
 
-/**
-   Bitwise OR of SerdNodeFlag values.
-*/
-typedef uint32_t SerdNodeFlags;
-
-/**
-   A syntactic RDF node.
-*/
+/// A syntactic RDF node
 typedef struct SerdNodeImpl SerdNode;
 
-/**
-   An unterminated immutable slice of a string.
-*/
+/// An unterminated immutable slice of a string
 typedef struct {
-	const char* buf;  /**< Start of chunk */
-	size_t      len;  /**< Length of chunk in bytes */
+	const char* buf;  ///< Start of chunk
+	size_t      len;  ///< Length of chunk in bytes
 } SerdStringView;
 
-/**
-   A mutable buffer in memory.
-*/
+/// A mutable buffer in memory
 typedef struct {
-	void*  buf;  /**< Buffer */
-	size_t len;  /**< Size of buffer in bytes */
+	void*  buf;  ///< Buffer
+	size_t len;  ///< Size of buffer in bytes
 } SerdBuffer;
 
-/**
-   An error description.
-*/
+/// An error description
 typedef struct {
 	SerdStatus        status;  /**< Error code */
 	const SerdCursor* cursor;  /**< Origin of error, or NULL */
@@ -282,23 +201,23 @@ typedef struct {
 } SerdError;
 
 /**
-   A parsed URI.
+   A parsed URI
 
    This struct directly refers to slices in other strings, it does not own any
    memory itself.  Thus, URIs can be parsed and/or resolved against a base URI
    in-place without allocating memory.
 */
 typedef struct {
-	SerdStringView scheme;     /**< Scheme */
-	SerdStringView authority;  /**< Authority */
-	SerdStringView path_base;  /**< Path prefix if relative */
-	SerdStringView path;       /**< Path suffix */
-	SerdStringView query;      /**< Query */
-	SerdStringView fragment;   /**< Fragment */
+	SerdStringView scheme;     ///< Scheme
+	SerdStringView authority;  ///< Authority
+	SerdStringView path_base;  ///< Path prefix if relative
+	SerdStringView path;       ///< Path suffix
+	SerdStringView query;      ///< Query
+	SerdStringView fragment;   ///< Fragment
 } SerdURI;
 
 /**
-   Writer style options.
+   Writer style options
 
    The style of the writer output can be controlled by ORing together
    values from this enumeration.  Note that some options are only supported
@@ -306,16 +225,14 @@ typedef struct {
    always ASCII).
 */
 typedef enum {
-	SERD_STYLE_ASCII = 1 << 0,  /**< Escape all non-ASCII characters. */
+	SERD_STYLE_ASCII = 1 << 0,  ///< Escape all non-ASCII characters
 } SerdWriterFlag;
 
-/**
-   Bitwise OR of SerdWriterFlag values.
-*/
+/// Bitwise OR of SerdWriterFlag values
 typedef uint32_t SerdWriterFlags;
 
 /**
-   Free memory allocated by Serd.
+   Free memory allocated by Serd
 
    This function exists because some systems require memory allocated by a
    library to be freed by code in the same library.  It is otherwise equivalent
@@ -330,15 +247,14 @@ serd_free(void* ptr);
    @{
 */
 
-/**
-   Return a string describing a status code.
-*/
+/// Return a string describing a status code
 SERD_API
 const char*
 serd_strerror(SerdStatus status);
 
 /**
-   Measure a UTF-8 string.
+   Measure a UTF-8 string
+
    @return Length of `str` in bytes.
    @param str A null-terminated UTF-8 string.
    @param flags (Output) Set to the applicable flags.
@@ -348,7 +264,7 @@ size_t
 serd_strlen(const char* str, SerdNodeFlags* flags);
 
 /**
-   Parse a string to a double.
+   Parse a string to a double
 
    The API of this function is similar to the standard C strtod function,
    except this function is locale-independent and always matches the lexical
@@ -367,7 +283,7 @@ serd_strtod(const char* str, size_t* end);
 */
 
 /**
-   Return the number of bytes required to encode `size` bytes in base64.
+   Return the number of bytes required to encode `size` bytes in base64
 
    @param size The number of input (binary) bytes to encode.
    @param wrap_lines Wrap lines at 76 characters to conform to RFC 2045.
@@ -378,7 +294,7 @@ size_t
 serd_base64_encoded_length(size_t size, bool wrap_lines);
 
 /**
-   Return the maximum number of bytes required to decode `size` bytes of base64.
+   Return the maximum number of bytes required to decode `size` bytes of base64
 
    @param len The number of input (text) bytes to decode.
    @return The required buffer size to decode `size` bytes of base64.
@@ -388,7 +304,7 @@ size_t
 serd_base64_decoded_size(size_t len);
 
 /**
-   Encode `size` bytes of `buf` into `str`, which must be large enough.
+   Encode `size` bytes of `buf` into `str`, which must be large enough
 
    @param str Output buffer of at least serd_base64_encoded_length(size) bytes.
    @param buf Input binary data.
@@ -401,7 +317,7 @@ bool
 serd_base64_encode(char* str, const void* buf, size_t size, bool wrap_lines);
 
 /**
-   Decode a base64 string.
+   Decode a base64 string
 
    This function can be used to deserialise a blob node created with
    serd_new_blob().
@@ -422,7 +338,7 @@ serd_base64_decode(void* buf, size_t* size, const char* str, size_t len);
 */
 
 /**
-   Function to detect I/O stream errors.
+   Function to detect I/O stream errors
 
    Identical semantics to `ferror`.
 
@@ -431,7 +347,7 @@ serd_base64_decode(void* buf, size_t* size, const char* str, size_t len);
 typedef int (*SerdStreamErrorFunc)(void* stream);
 
 /**
-   Source function for raw string input.
+   Source function for raw string input
 
    Identical semantics to `fread`, but may set errno for more informative error
    reporting than supported by SerdStreamErrorFunc.
@@ -448,7 +364,7 @@ typedef size_t (*SerdReadFunc)(void*  buf,
                                void*  stream);
 
 /**
-   Sink function for raw string output.
+   Sink function for raw string output
 
    Identical semantics to `fwrite`, but may set errno for more informative
    error reporting than supported by SerdStreamErrorFunc.
@@ -465,7 +381,7 @@ typedef size_t (*SerdWriteFunc)(const void* buf,
                                 void*       stream);
 
 /**
-   Create a new byte sink.
+   Create a new byte sink
 
    @param write_func Function called with bytes to consume.
    @param stream Context parameter passed to `sink`.
@@ -476,7 +392,7 @@ SerdByteSink*
 serd_byte_sink_new(SerdWriteFunc write_func, void* stream, size_t block_size);
 
 /**
-   Write to `sink`.
+   Write to `sink`
 
    Compatible with SerdWriteFunc.
 */
@@ -487,16 +403,12 @@ serd_byte_sink_write(const void*   buf,
                      size_t        nmemb,
                      SerdByteSink* sink);
 
-/**
-   Flush any pending output in `sink` to the underlying write function.
-*/
+/// Flush any pending output in `sink` to the underlying write function
 SERD_API
 void
 serd_byte_sink_flush(SerdByteSink* sink);
 
-/**
-   Free `sink`.
-*/
+/// Free `sink`
 SERD_API
 void
 serd_byte_sink_free(SerdByteSink* sink);
@@ -508,7 +420,7 @@ serd_byte_sink_free(SerdByteSink* sink);
 */
 
 /**
-   Get a syntax by name.
+   Get a syntax by name
 
    Case-insensitive, supports "Turtle", "NTriples", "NQuads", and "TriG".  Zero
    is returned if the name is not recognized.
@@ -518,7 +430,7 @@ SerdSyntax
 serd_syntax_by_name(const char* name);
 
 /**
-   Guess a syntax from a filename.
+   Guess a syntax from a filename
 
    This uses the file extension to guess the syntax of a file.  Zero is
    returned if the extension is not recognized.
@@ -528,7 +440,7 @@ SerdSyntax
 serd_guess_syntax(const char* filename);
 
 /**
-   Guess a syntax from a filename.
+   Guess a syntax from a filename
 
    This uses the file extension to guess the syntax of a file.  Zero is
    returned if the extension is not recognized.
@@ -548,52 +460,47 @@ static const SerdURI SERD_URI_NULL = {
 };
 
 /**
-   Get the unescaped path and hostname from a file URI.
+   Get the unescaped path and hostname from a file URI
+
+   The returned path and `*hostname` must be freed with serd_free().
+
    @param uri A file URI.
    @param hostname If non-NULL, set to the hostname, if present.
    @return The path component of the URI.
-
-   The returned path and `*hostname` must be freed with serd_free().
 */
 SERD_API
 char*
 serd_file_uri_parse(const char* uri, char** hostname);
 
-/**
-   Return true iff `utf8` starts with a valid URI scheme.
-*/
+/// Return true iff `utf8` starts with a valid URI scheme
 SERD_API
 bool
 serd_uri_string_has_scheme(const char* utf8);
 
-/**
-   Parse `utf8`, writing result to `out`.
-*/
+/// Parse `utf8`, writing result to `out`
 SERD_API
 SerdStatus
 serd_uri_parse(const char* utf8, SerdURI* out);
 
 /**
-   Set target `t` to reference `r` resolved against `base`.
+   Set target `t` to reference `r` resolved against `base`
 
-   @see http://tools.ietf.org/html/rfc3986#section-5.2.2
+   @see [RFC3986 5.2.2](http://tools.ietf.org/html/rfc3986#section-5.2.2)
 */
 SERD_API
 void
 serd_uri_resolve(const SerdURI* r, const SerdURI* base, SerdURI* t);
 
-/**
-   Serialise `uri` with a series of calls to `sink`.
-*/
+/// Serialise `uri` with a series of calls to `sink`
 SERD_API
 size_t
 serd_uri_serialise(const SerdURI* uri, SerdWriteFunc sink, void* stream);
 
 /**
-   Serialise `uri` relative to `base` with a series of calls to `sink`.
+   Serialise `uri` relative to `base` with a series of calls to `sink`
 
-   The `uri` is written as a relative URI iff if it a child of `base` and @c
-   root.  The optional `root` parameter must be a prefix of `base` and can be
+   The `uri` is written as a relative URI iff if it a child of `base` and
+   `root`.  The optional `root` parameter must be a prefix of `base` and can be
    used keep up-references ("../") within a certain namespace.
 */
 SERD_API
@@ -622,16 +529,12 @@ SERD_API
 SerdNode*
 serd_new_simple_node(SerdNodeType type, const char* str, size_t len);
 
-/**
-   Create a new plain literal string node from `str`.
-*/
+/// Create a new plain literal string node from `str`
 SERD_API
 SerdNode*
 serd_new_string(const char* str);
 
-/**
-   Create a new plain literal string node from a prefix of `str`.
-*/
+/// Create a new plain literal string node from a prefix of `str`.
 SERD_API
 SerdNode*
 serd_new_substring(const char* str, size_t len);
@@ -664,7 +567,7 @@ serd_new_literal(const char* str,
                  size_t      lang_len);
 
 /**
-   Create a new literal node from `str`.
+   Create a new plain literal node from `str`
 
    A plain literal has no datatype, but may have a language tag.  The `lang`
    may be NULL, in which case this is equivalent to `serd_new_string()`.
@@ -674,7 +577,7 @@ SerdNode*
 serd_new_plain_literal(const char* str, const char* lang);
 
 /**
-   Create a new typed literal node from `str`.
+   Create a new typed literal node from `str`
 
    A typed literal has no language tag, but may have a datatype.  The
    `datatype` may be NULL, in which case this is equivalent to
@@ -684,36 +587,28 @@ SERD_API
 SerdNode*
 serd_new_typed_literal(const char* str, const SerdNode* datatype);
 
-/**
-   Create a new blank node.
-*/
+/// Create a new blank node
 SERD_API
 SerdNode*
 serd_new_blank(const char* str);
 
-/**
-   Create a new CURIE node.
-*/
+/// Create a new CURIE node
 SERD_API
 SerdNode*
 serd_new_curie(const char* str);
 
-/**
-   Return a deep copy of `node`.
-*/
+/// Return a deep copy of `node`
 SERD_API
 SerdNode*
 serd_node_copy(const SerdNode* node);
 
-/**
-   Return true iff `a` is equal to `b`.
-*/
+/// Return true iff `a` is equal to `b`
 SERD_API
 bool
 serd_node_equals(const SerdNode* a, const SerdNode* b);
 
 /**
-   Compare two nodes.
+   Compare two nodes
 
    Returns less than, equal to, or greater than zero if `a` is less than, equal
    to, or greater than `b`, respectively.  NULL is treated as less than any
@@ -723,22 +618,18 @@ SERD_API
 int
 serd_node_compare(const SerdNode* a, const SerdNode* b);
 
-/**
-   Create a new URI from a string.
-*/
+/// Create a new URI from a string
 SERD_API
 SerdNode*
 serd_new_uri(const char* str);
 
-/**
-   Create a new URI from a string, resolved against a base URI.
-*/
+/// Create a new URI from a string, resolved against a base URI
 SERD_API
 SerdNode*
 serd_new_resolved_uri(const char* str, const SerdNode* base);
 
 /**
-   Resolve `node` against `base`.
+   Resolve `node` against `base`
 
    If `node` is not a relative URI, an equivalent new node is returned.
 */
@@ -747,7 +638,7 @@ SerdNode*
 serd_node_resolve(const SerdNode* node, const SerdNode* base);
 
 /**
-   Create a new file URI node from a file system path and optional hostname.
+   Create a new file URI node from a file system path and optional hostname
 
    Backslashes in Windows paths will be converted, and other characters will be
    percent encoded as necessary.
@@ -760,17 +651,15 @@ SerdNode*
 serd_new_file_uri(const char* path, const char* hostname);
 
 /**
-   Create a new URI from a string, relative to a base URI.
-
-   @param str URI string.
-
-   @param base Base URI to make `str` relative to, if possible.
-
-   @param root Optional root URI for resolution.
+   Create a new URI from a string, relative to a base URI
 
    The URI is made relative iff if it a child of `base` and `root`.  The
    optional `root` parameter must be a prefix of `base` and can be used keep
    up-references ("../") within a certain namespace.
+
+   @param str URI string.
+   @param base Base URI to make `str` relative to, if possible.
+   @param root Optional root URI for resolution.
 */
 SERD_API
 SerdNode*
@@ -779,7 +668,7 @@ serd_new_relative_uri(const char*     str,
                       const SerdNode* root);
 
 /**
-   Create a new node by serialising `d` into an xsd:decimal string.
+   Create a new node by serialising `d` into an xsd:decimal string
 
    The resulting node will always contain a `.', start with a digit, and end
    with a digit (i.e. will have a leading and/or trailing `0' if necessary).
@@ -791,41 +680,33 @@ serd_new_relative_uri(const char*     str,
    represent a double and float, respectively.
 
    @param d The value for the new node.
-
    @param frac_digits The maximum number of digits after the decimal place.
-
-   @param datatype Datatype of node, may be NULL in which case the node has
-   type xsd:decimal.
+   @param datatype Datatype of node, or NULL for xsd:decimal.
 */
 SERD_API
 SerdNode*
 serd_new_decimal(double d, unsigned frac_digits, const SerdNode* datatype);
 
 /**
-   Create a new node by serialising `i` into an xsd:integer string.
+   Create a new node by serialising `i` into an xsd:integer string
 
    @param i Integer value to serialise.
-
-   @param datatype Datatype of node, may be NULL in which case the node has
-   type xsd:integer.
+   @param datatype Datatype of node, or NULL for xsd:integer.
 */
 SERD_API
 SerdNode*
 serd_new_integer(int64_t i, const SerdNode* datatype);
 
 /**
-   Create a node by serialising `buf` into an xsd:base64Binary string.
+   Create a node by serialising `buf` into an xsd:base64Binary string
+
    This function can be used to make a serialisable node out of arbitrary
    binary data, which can be decoded using serd_base64_decode().
 
    @param buf Raw binary input data.
-
    @param size Size of `buf`.
-
    @param wrap_lines Wrap lines at 76 characters to conform to RFC 2045.
-
-   @param datatype Datatype of node, may be NULL in which case the node has
-   type xsd:base64Binary.
+   @param datatype Datatype of node, or NULL for xsd:base64Binary.
 */
 SERD_API
 SerdNode*
@@ -834,54 +715,37 @@ serd_new_blob(const void*     buf,
               bool            wrap_lines,
               const SerdNode* datatype);
 
-/**
-   Return the type of a node (SERD_URI, SERD_BLANK, or SERD_LITERAL).
-*/
+/// Return the type of a node (SERD_URI, SERD_BLANK, or SERD_LITERAL)
 SERD_API
 SerdNodeType
 serd_node_get_type(const SerdNode* node);
 
-/**
-   Return the string value of a node.
-*/
+/// Return the string value of a node
 SERD_API
 const char*
 serd_node_get_string(const SerdNode* node);
 
-/**
-   Return the length of the string value of a node in bytes.
-*/
+/// Return the length of the string value of a node in bytes
 SERD_API
 size_t
 serd_node_get_length(const SerdNode* node);
 
-/**
-   Return the datatype of a literal node, or NULL.
-*/
+/// Return the datatype of a literal node, or NULL
 SERD_API
 const SerdNode*
 serd_node_get_datatype(const SerdNode* node);
 
-/**
-   Return the language tag of a literal node, or NULL.
-*/
+/// Return the language tag of a literal node, or NULL
 SERD_API
 const SerdNode*
 serd_node_get_language(const SerdNode* node);
 
-/**
-   Return the flags (string properties) of a node.
-*/
+/// Return the flags (string properties) of a node
 SERD_API
 SerdNodeFlags
 serd_node_get_flags(const SerdNode* node);
 
-/**
-   Free any data owned by `node`.
-
-   Note that if `node` is itself dynamically allocated (which is not the case
-   for nodes created internally by serd), it will not be freed.
-*/
+/// Free `node`
 SERD_API
 void
 serd_node_free(SerdNode* node);
@@ -902,15 +766,14 @@ typedef SerdStatus (*SerdErrorSink)(void*            handle,
                                     const SerdError* error);
 
 /**
-   Sink (callback) for base URI changes.
+   Sink (callback) for base URI changes
 
    Called whenever the base URI of the serialisation changes.
 */
-typedef SerdStatus (*SerdBaseSink)(void*           handle,
-                                   const SerdNode* uri);
+typedef SerdStatus (*SerdBaseSink)(void* handle, const SerdNode* uri);
 
 /**
-   Sink (callback) for namespace definitions.
+   Sink (callback) for namespace definitions
 
    Called whenever a prefix is defined in the serialisation.
 */
@@ -919,7 +782,7 @@ typedef SerdStatus (*SerdPrefixSink)(void*           handle,
                                      const SerdNode* uri);
 
 /**
-   Sink (callback) for statements.
+   Sink (callback) for statements
 
    Called for every RDF statement in the serialisation.
 */
@@ -928,14 +791,13 @@ typedef SerdStatus (*SerdStatementSink)(void*                handle,
                                         const SerdStatement* statement);
 
 /**
-   Sink (callback) for anonymous node end markers.
+   Sink (callback) for anonymous node end markers
 
    This is called to indicate that the anonymous node with the given
    `value` will no longer be referred to by any future statements
    (i.e. the anonymous serialisation of the node is finished).
 */
-typedef SerdStatus (*SerdEndSink)(void*           handle,
-                                  const SerdNode* node);
+typedef SerdStatus (*SerdEndSink)(void* handle, const SerdNode* node);
 
 /**
    @}
@@ -944,7 +806,7 @@ typedef SerdStatus (*SerdEndSink)(void*           handle,
 */
 
 /**
-   Create a new Serd World.
+   Create a new World
 
    It is safe to use multiple worlds in one process, though no objects can be
    shared between worlds.
@@ -953,15 +815,13 @@ SERD_API
 SerdWorld*
 serd_world_new(void);
 
-/**
-   Free `world`.
-*/
+/// Free `world`
 SERD_API
 void
 serd_world_free(SerdWorld* world);
 
 /**
-   Return the nodes cache in `world`.
+   Return the nodes cache in `world`
 
    The returned cache is owned by the world and contains various nodes used
    frequently by the implementation.  For convenience, it may be used to store
@@ -972,7 +832,7 @@ SerdNodes*
 serd_world_get_nodes(SerdWorld* world);
 
 /**
-   Return a unique blank node.
+   Return a unique blank node
 
    The returned node is valid only until the next time serd_world_get_blank()
    is called or the world is destroyed.
@@ -999,58 +859,42 @@ serd_world_set_error_sink(SerdWorld*    world,
    @{
 */
 
-/**
-   Create a new environment.
-*/
+/// Create a new environment
 SERD_API
 SerdEnv*
 serd_env_new(const SerdNode* base_uri);
 
-/**
-   Copy an environment.
-*/
+/// Copy an environment
 SERD_API
 SerdEnv*
 serd_env_copy(const SerdEnv* env);
 
-/**
-   Return true iff `a` is equal to `b`.
-*/
+/// Return true iff `a` is equal to `b`
 SERD_API
 bool
 serd_env_equals(const SerdEnv* a, const SerdEnv* b);
 
-/**
-   Free `ns`.
-*/
+/// Free `env`
 SERD_API
 void
 serd_env_free(SerdEnv* env);
 
-/**
-   Get the current base URI.
-*/
+/// Get the current base URI
 SERD_API
 const SerdNode*
 serd_env_get_base_uri(const SerdEnv* env);
 
-/**
-   Set the current base URI.
-*/
+/// Set the current base URI
 SERD_API
 SerdStatus
 serd_env_set_base_uri(SerdEnv* env, const SerdNode* uri);
 
-/**
-   Set a namespace prefix.
-*/
+/// Set a namespace prefix
 SERD_API
 SerdStatus
 serd_env_set_prefix(SerdEnv* env, const SerdNode* name, const SerdNode* uri);
 
-/**
-   Set a namespace prefix.
-*/
+/// Set a namespace prefix
 SERD_API
 SerdStatus
 serd_env_set_prefix_from_strings(SerdEnv*    env,
@@ -1058,7 +902,7 @@ serd_env_set_prefix_from_strings(SerdEnv*    env,
                                  const char* uri);
 
 /**
-   Qualify `uri` into a CURIE if possible.
+   Qualify `uri` into a CURIE if possible
 
    Returns null if `node` can not be qualified.
 */
@@ -1067,7 +911,9 @@ SerdNode*
 serd_env_qualify(const SerdEnv* env, const SerdNode* uri);
 
 /**
-   Expand `node`, which must be a CURIE or URI, to a full URI.
+   Expand `node`, transforming CURIEs into URIs
+
+   If `node` is a literal, its datatype is expanded if necessary.
 
    Returns null if `node` can not be expanded.
 */
@@ -1075,9 +921,7 @@ SERD_API
 SerdNode*
 serd_env_expand(const SerdEnv* env, const SerdNode* node);
 
-/**
-   Write all prefixes in `env` to `sink`.
-*/
+/// Write all prefixes in `env` to `sink`
 SERD_API
 void
 serd_env_write_prefixes(const SerdEnv* env, const SerdSink* sink);
@@ -1089,7 +933,7 @@ serd_env_write_prefixes(const SerdEnv* env, const SerdSink* sink);
 */
 
 /**
-   Create a new sink.
+   Create a new sink
 
    Initially, the sink has no set functions and will do nothing.  Use the
    serd_sink_set_*_func functions to set handlers for various events.
@@ -1101,84 +945,56 @@ SERD_API
 SerdSink*
 serd_sink_new(void* handle, SerdEnv* env);
 
-/**
-   Free `sink`.
-*/
+/// Free `sink`
 SERD_API
 void
 serd_sink_free(SerdSink* sink);
 
-/**
-   Return the env used by `writer`.
-*/
+/// Return the env used by `sink`
 SERD_API
 const SerdEnv*
 serd_sink_get_env(const SerdSink* sink);
 
-/**
-   Set a function to be called when the base URI changes.
-*/
+/// Set a function to be called when the base URI changes
 SERD_API
 SerdStatus
 serd_sink_set_base_func(SerdSink* sink, SerdBaseSink base_func);
 
-/**
-   Set a function to be called when a namespace prefix is defined.
-*/
+/// Set a function to be called when a namespace prefix is defined
 SERD_API
 SerdStatus
 serd_sink_set_prefix_func(SerdSink* sink, SerdPrefixSink prefix_func);
 
-/**
-   Set a function to be called when a statement is emitted.
-*/
+/// Set a function to be called when a statement is emitted
 SERD_API
 SerdStatus
 serd_sink_set_statement_func(SerdSink* sink, SerdStatementSink statement_func);
 
-/**
-   Set a function to be called when an anonymous node ends.
-*/
+/// Set a function to be called when an anonymous node ends
 SERD_API
 SerdStatus
 serd_sink_set_end_func(SerdSink* sink, SerdEndSink end_func);
 
-/**
-   Set the base URI.
-
-   Simple wrapper for the `SerdBaseSink` of `sink`.
-*/
+/// Set the base URI
 SERD_API
 SerdStatus
 serd_sink_write_base(const SerdSink* sink, const SerdNode* uri);
 
-/**
-   Set a namespace prefix.
-
-   Simple wrapper for the `SerdPrefixSink` of `sink`.
-*/
+/// Set a namespace prefix
 SERD_API
 SerdStatus
 serd_sink_write_prefix(const SerdSink* sink,
                        const SerdNode* name,
                        const SerdNode* uri);
 
-/**
-   Write a statement.
-
-   Simple wrapper for the `SerdStatementSink` of `sink`.
-*/
+/// Write a statement
 SERD_API
 SerdStatus
 serd_sink_write_statement(const SerdSink*      sink,
                           SerdStatementFlags   flags,
                           const SerdStatement* statement);
 
-/**
-   Write a statement from individual nodes.
-
-   Simple wrapper for the `SerdStatementSink` of `sink`.
-*/
+/// Write a statement from individual nodes
 SERD_API
 SerdStatus
 serd_sink_write(const SerdSink*    sink,
@@ -1188,11 +1004,7 @@ serd_sink_write(const SerdSink*    sink,
                 const SerdNode*    object,
                 const SerdNode*    graph);
 
-/**
-   Mark the end of an anonymous node.
-
-   Simple wrapper for the `SerdEndSink` of `sink`.
-*/
+/// Mark the end of an anonymous node
 SERD_API
 SerdStatus
 serd_sink_write_end(const SerdSink* sink, const SerdNode* node);
@@ -1203,9 +1015,7 @@ serd_sink_write_end(const SerdSink* sink, const SerdNode* node);
    @{
 */
 
-/**
-   Create a new RDF reader.
-*/
+/// Create a new RDF reader
 SERD_API
 SerdReader*
 serd_reader_new(SerdWorld*      world,
@@ -1214,7 +1024,7 @@ serd_reader_new(SerdWorld*      world,
                 size_t          stack_size);
 
 /**
-   Enable or disable strict parsing.
+   Enable or disable strict parsing
 
    The reader is non-strict (lax) by default, which will tolerate URIs with
    invalid characters.  Setting strict will fail when parsing such files.  An
@@ -1225,7 +1035,7 @@ void
 serd_reader_set_strict(SerdReader* reader, bool strict);
 
 /**
-   Set a prefix to be added to all blank node identifiers.
+   Set a prefix to be added to all blank node identifiers
 
    This is useful when multiple files are to be parsed into the same output
    (e.g. a store, or other files).  Since Serd preserves blank node IDs, this
@@ -1235,18 +1045,15 @@ serd_reader_set_strict(SerdReader* reader, bool strict);
 */
 SERD_API
 void
-serd_reader_add_blank_prefix(SerdReader* reader,
-                             const char* prefix);
+serd_reader_add_blank_prefix(SerdReader* reader, const char* prefix);
 
-/**
-   Prepare to read from the file at a local file `uri`.
-*/
+/// Prepare to read from the file at a local file `uri`
 SERD_API
 SerdStatus
 serd_reader_start_file(SerdReader* reader, const char* uri, bool bulk);
 
 /**
-   Prepare to read from a stream.
+   Prepare to read from a stream
 
    The `read_func` is guaranteed to only be called for `page_size` elements
    with size 1 (i.e. `page_size` bytes).
@@ -1260,9 +1067,7 @@ serd_reader_start_stream(SerdReader*         reader,
                          const SerdNode*     name,
                          size_t              page_size);
 
-/**
-   Prepare to read from a string.
-*/
+/// Prepare to read from a string
 SERD_API
 SerdStatus
 serd_reader_start_string(SerdReader*     reader,
@@ -1270,7 +1075,7 @@ serd_reader_start_string(SerdReader*     reader,
                          const SerdNode* name);
 
 /**
-   Read a single "chunk" of data during an incremental read.
+   Read a single "chunk" of data during an incremental read
 
    This function will read a single top level description, and return.  This
    may be a directive, statement, or several statements; essentially it reads
@@ -1282,7 +1087,7 @@ SerdStatus
 serd_reader_read_chunk(SerdReader* reader);
 
 /**
-   Read a complete document from the source.
+   Read a complete document from the source
 
    This function will continue pulling from the source until a complete
    document has been read.  Note that this may block when used with streams,
@@ -1293,7 +1098,7 @@ SerdStatus
 serd_reader_read_document(SerdReader* reader);
 
 /**
-   Finish reading from the source.
+   Finish reading from the source
 
    This will close the open file, if applicable, and ensure the reader has
    processed all input.
@@ -1303,7 +1108,7 @@ SerdStatus
 serd_reader_finish(SerdReader* reader);
 
 /**
-   Free `reader`.
+   Free `reader`
 
    The reader will be finished via `serd_reader_finish()` if necessary.
 */
@@ -1317,9 +1122,7 @@ serd_reader_free(SerdReader* reader);
    @{
 */
 
-/**
-   Create a new RDF writer.
-*/
+/// Create a new RDF writer
 SERD_API
 SerdWriter*
 serd_writer_new(SerdWorld*      world,
@@ -1329,22 +1132,18 @@ serd_writer_new(SerdWorld*      world,
                 SerdWriteFunc   write_func,
                 void*           stream);
 
-/**
-   Free `writer`.
-*/
+/// Free `writer`
 SERD_API
 void
 serd_writer_free(SerdWriter* writer);
 
-/**
-   Return a sink interface that emits statements via `writer`.
-*/
+/// Return a sink interface that emits statements via `writer`
 SERD_API
 const SerdSink*
 serd_writer_get_sink(SerdWriter* writer);
 
 /**
-   A convenience sink function for writing to a string.
+   A convenience sink function for writing to a string
 
    This function can be used as a SerdSink to write to a SerdBuffer which is
    resized as necessary with realloc().  The `stream` parameter must point to
@@ -1356,35 +1155,31 @@ size_t
 serd_buffer_sink(const void* buf, size_t size, size_t nmemb, void* stream);
 
 /**
-   Finish a serialisation to a buffer with serd_buffer_sink().
+   Finish a serialisation to a buffer with serd_buffer_sink()
 
-   The returned string is the result of the serialisation, which is NULL
+   The returned string is the result of the serialisation, which is null
    terminated (by this function) and owned by the caller.
 */
 SERD_API
 char*
 serd_buffer_sink_finish(SerdBuffer* stream);
 
-/**
-   Set a prefix to be removed from matching blank node identifiers.
-*/
+/// Set a prefix to be removed from matching blank node identifiers
 SERD_API
 void
-serd_writer_chop_blank_prefix(SerdWriter* writer,
-                              const char* prefix);
+serd_writer_chop_blank_prefix(SerdWriter* writer, const char* prefix);
 
 /**
-   Set the current output base URI (and emit directive if applicable).
+   Set the current output base URI (and emit directive if applicable)
 
    Note this function can be safely casted to SerdBaseSink.
 */
 SERD_API
 SerdStatus
-serd_writer_set_base_uri(SerdWriter*     writer,
-                         const SerdNode* uri);
+serd_writer_set_base_uri(SerdWriter* writer, const SerdNode* uri);
 
 /**
-   Set the current root URI.
+   Set the current root URI
 
    The root URI should be a prefix of the base URI.  The path of the root URI
    is the highest path any relative up-reference can refer to.  For example,
@@ -1395,12 +1190,9 @@ serd_writer_set_base_uri(SerdWriter*     writer,
 */
 SERD_API
 SerdStatus
-serd_writer_set_root_uri(SerdWriter*     writer,
-                         const SerdNode* uri);
+serd_writer_set_root_uri(SerdWriter* writer, const SerdNode* uri);
 
-/**
-   Finish a write.
-*/
+/// Finish a write
 SERD_API
 SerdStatus
 serd_writer_finish(SerdWriter* writer);
@@ -1411,15 +1203,13 @@ serd_writer_finish(SerdWriter* writer);
    @{
 */
 
-/**
-   Create a new node set.
-*/
+/// Create a new node set
 SERD_API
 SerdNodes*
 serd_nodes_new(void);
 
 /**
-   Free `nodes` and all nodes that are stored in it.
+   Free `nodes` and all nodes that are stored in it
 
    Note that this invalidates any pointers previously returned from
    `serd_nodes_intern()` or `serd_nodes_manage()` calls on `nodes`.
@@ -1429,7 +1219,7 @@ void
 serd_nodes_free(SerdNodes* nodes);
 
 /**
-   Intern `node`.
+   Intern `node`
 
    Multiple calls with equivalent nodes will return the same pointer.
 
@@ -1440,7 +1230,7 @@ const SerdNode*
 serd_nodes_intern(SerdNodes* nodes, const SerdNode* node);
 
 /**
-   Manage `node`.
+   Manage `node`
 
    Like `serd_nodes_intern`, but takes ownership of `node`, freeing it and
    returning a previously interned/managed equivalent node if necessary.
@@ -1452,7 +1242,7 @@ const SerdNode*
 serd_nodes_manage(SerdNodes* nodes, SerdNode* node);
 
 /**
-   Dereference `node`.
+   Dereference `node`
 
    Decrements the reference count of `node`, and frees the internally stored
    equivalent node if this was the last reference.  Does nothing if no node
@@ -1468,44 +1258,32 @@ serd_nodes_deref(SerdNodes* nodes, const SerdNode* node);
    @{
 */
 
-/**
-   Return the given node in `statement`.
-*/
+/// Return the given node in `statement`
 SERD_API
 const SerdNode*
 serd_statement_get_node(const SerdStatement* statement, SerdField field);
 
-/**
-   Return the subject in `statement`.
-*/
+/// Return the subject in `statement`
 SERD_API
 const SerdNode*
 serd_statement_get_subject(const SerdStatement* statement);
 
-/**
-   Return the predicate in `statement`.
-*/
+/// Return the predicate in `statement`
 SERD_API
 const SerdNode*
 serd_statement_get_predicate(const SerdStatement* statement);
 
-/**
-   Return the object in `statement`.
-*/
+/// Return the object in `statement`
 SERD_API
 const SerdNode*
 serd_statement_get_object(const SerdStatement* statement);
 
-/**
-   Return the graph in `statement`.
-*/
+/// Return the graph in `statement`
 SERD_API
 const SerdNode*
 serd_statement_get_graph(const SerdStatement* statement);
 
-/**
-   Return the source location where `statement` originated, or NULL.
-*/
+/// Return the source location where `statement` originated, or NULL
 SERD_API
 const SerdCursor*
 serd_statement_get_cursor(const SerdStatement* statement);
@@ -1551,7 +1329,7 @@ bool
 serd_cursor_equals(const SerdCursor* lhs, const SerdCursor* rhs);
 
 /**
-   Return the document name.
+   Return the document name
 
    This is typically a file URI, but may be a descriptive string node for
    statements that originate from streams.
@@ -1560,16 +1338,12 @@ SERD_API
 const SerdNode*
 serd_cursor_get_name(const SerdCursor* cursor);
 
-/**
-   Return the one-relative line number in the document.
-*/
+/// Return the one-relative line number in the document
 SERD_API
 unsigned
 serd_cursor_get_line(const SerdCursor* cursor);
 
-/**
-   Return the zero-relative column number in the line.
-*/
+/// Return the zero-relative column number in the line
 SERD_API
 unsigned
 serd_cursor_get_column(const SerdCursor* cursor);