Use Markdown in doc comments for better source readability.

git-svn-id: http://svn.drobilla.net/serd/trunk@470 490d8e77-9747-427b-9fa3-0b8f29cee8a0

1 files changed, 46 insertions, 46 deletions

diff --git a/serd/serd.h b/serd/serd.h
index c06cfc1f..635c9928 100644
--- a/serd/serd.h
+++ b/serd/serd.h
@@ -277,9 +277,9 @@ serd_strerror(SerdStatus status);
 
 /**
    Measure a UTF-8 string.
-   @return Length of @c str in characters (except NULL).
+   @return Length of `str` in characters (except NULL).
    @param str A null-terminated UTF-8 string.
-   @param n_bytes (Output) Set to the size of @c str in bytes (except NULL).
+   @param n_bytes (Output) Set to the size of `str` in bytes (except NULL).
    @param flags (Output) Set to the applicable flags.
 */
 SERD_API
@@ -303,7 +303,7 @@ serd_strtod(const char* str, char** endptr);
    serd_node_new_blob().
 
    @param str Base64 string to decode.
-   @param len The length of @c str.
+   @param len The length of `str`.
    @param size Set to the size of the returned blob in bytes.
    @return A newly allocated blob which must be freed with free().
 */
@@ -320,9 +320,9 @@ serd_base64_decode(const uint8_t* str, size_t len, size_t* size);
 static const SerdURI SERD_URI_NULL = {{0,0},{0,0},{0,0},{0,0},{0,0},{0,0}};
 
 /**
-   Return the local path for @c uri, or NULL if @c uri is not a file URI.
+   Return the local path for `uri`, or NULL if `uri` is not a file URI.
    Note this (inappropriately named) function only removes the file scheme if
-   necessary, and returns @c uri unmodified if it is an absolute path.  Percent
+   necessary, and returns `uri` unmodified if it is an absolute path.  Percent
    encoding and other issues are not handled, to properly convert a file URI to
    a path, use serd_file_uri_parse().
 */
@@ -336,7 +336,7 @@ serd_uri_to_path(const uint8_t* uri);
    @param hostname If non-NULL, set to the hostname, if present.
    @return The path component of the URI.
 
-   Both the returned path and @c hostname (if applicable) are owned by the
+   Both the returned path and `hostname` (if applicable) are owned by the
    caller and must be freed with free().
 */
 SERD_API
@@ -344,21 +344,21 @@ uint8_t*
 serd_file_uri_parse(const uint8_t* uri, uint8_t** hostname);
 
 /**
-   Return true iff @c 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 uint8_t* utf8);
 
 /**
-   Parse @c utf8, writing result to @c out.
+   Parse `utf8`, writing result to `out`.
 */
 SERD_API
 SerdStatus
 serd_uri_parse(const uint8_t* utf8, SerdURI* out);
 
 /**
-   Set @c out to @c uri resolved against @c base.
+   Set `out` to `uri` resolved against `base`.
 */
 SERD_API
 void
@@ -370,17 +370,17 @@ serd_uri_resolve(const SerdURI* uri, const SerdURI* base, SerdURI* out);
 typedef size_t (*SerdSink)(const void* buf, size_t len, void* stream);
 
 /**
-   Serialise @c uri with a series of calls to @c sink.
+   Serialise `uri` with a series of calls to `sink`.
 */
 SERD_API
 size_t
 serd_uri_serialise(const SerdURI* uri, SerdSink sink, void* stream);
 
 /**
-   Serialise @c uri relative to @c base with a series of calls to @c sink.
+   Serialise `uri` relative to `base` with a series of calls to `sink`.
 
-   The @c uri is written as a relative URI iff if it a child of @c base and @c
-   root.  The optional @c root parameter must be a prefix of @c base and can be
+   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
    used keep up-references ("../") within a certain namespace.
 */
 SERD_API
@@ -400,25 +400,25 @@ serd_uri_serialise_relative(const SerdURI* uri,
 static const SerdNode SERD_NODE_NULL = { 0, 0, 0, 0, SERD_NOTHING };
 
 /**
-   Make a (shallow) node from @c str.
+   Make a (shallow) node from `str`.
 
-   This measures, but does not copy, @c str.  No memory is allocated.
+   This measures, but does not copy, `str`.  No memory is allocated.
 */
 SERD_API
 SerdNode
 serd_node_from_string(SerdType type, const uint8_t* str);
 
 /**
-   Make a deep copy of @c node.
+   Make a deep copy of `node`.
 
-   @return a node that the caller must free with @ref serd_node_free.
+   @return a node that the caller must free with serd_node_free().
 */
 SERD_API
 SerdNode
 serd_node_copy(const SerdNode* node);
 
 /**
-   Return true iff @c a is equal to @c b.
+   Return true iff `a` is equal to `b`.
 */
 SERD_API
 bool
@@ -446,11 +446,11 @@ serd_node_new_uri_from_string(const uint8_t* str,
    Create a new file URI node from a file system path and optional hostname.
 
    Backslashes in Windows paths will be converted and '%' will always be
-   percent encoded.  If @c escape is true, all other invalid characters will be
+   percent encoded.  If `escape` is true, all other invalid characters will be
    percent encoded as well.
 
-   If @c path is relative, @c hostname is ignored.
-   If @c out is not NULL, it will be set to the parsed URI.
+   If `path` is relative, `hostname` is ignored.
+   If `out` is not NULL, it will be set to the parsed URI.
 */
 SERD_API
 SerdNode
@@ -460,11 +460,11 @@ serd_node_new_file_uri(const uint8_t* path,
                        bool           escape);
 
 /**
-   Create a new node by serialising @c uri into a new string.
+   Create a new node by serialising `uri` into a new string.
 
    @param uri The URI to parse and serialise.
 
-   @param base Base URI to resolve @c uri against (or NULL for no resolution).
+   @param base Base URI to resolve `uri` against (or NULL for no resolution).
 
    @param out Set to the parsing of the new URI (i.e. points only to
    memory owned by the new returned node).
@@ -474,13 +474,13 @@ SerdNode
 serd_node_new_uri(const SerdURI* uri, const SerdURI* base, SerdURI* out);
 
 /**
-   Create a new node by serialising @c 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).
-   It will never be in scientific notation.  A maximum of @c frac_digits digits
+   It will never be in scientific notation.  A maximum of `frac_digits` digits
    will be written after the decimal point, but trailing zeros will
-   automatically be omitted (except one if @c d is a round integer).
+   automatically be omitted (except one if `d` is a round integer).
 
    Note that about 16 and 8 fractional digits are required to precisely
    represent a double and float, respectively.
@@ -493,19 +493,19 @@ SerdNode
 serd_node_new_decimal(double d, unsigned frac_digits);
 
 /**
-   Create a new node by serialising @c i into an xsd:integer string.
+   Create a new node by serialising `i` into an xsd:integer string.
 */
 SERD_API
 SerdNode
 serd_node_new_integer(int64_t i);
 
 /**
-   Create a node by serialising @c 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 @c buf.
+   @param size Size of `buf`.
    @param wrap_lines Wrap lines at 76 characters to conform to RFC 2045.
 */
 SERD_API
@@ -513,9 +513,9 @@ SerdNode
 serd_node_new_blob(const void* buf, size_t size, bool wrap_lines);
 
 /**
-   Free any data owned by @c node.
+   Free any data owned by `node`.
 
-   Note that if @c node is itself dynamically allocated (which is not the case
+   Note that if `node` is itself dynamically allocated (which is not the case
    for nodes created internally by serd), it will not be freed.
 */
 SERD_API
@@ -572,7 +572,7 @@ typedef SerdStatus (*SerdStatementSink)(void*              handle,
    Sink (callback) for anonymous node end markers.
 
    This is called to indicate that the anonymous node with the given
-   @c value will no longer be referred to by any future statements
+   `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,
@@ -592,7 +592,7 @@ SerdEnv*
 serd_env_new(const SerdNode* base_uri);
 
 /**
-   Free @c ns.
+   Free `ns`.
 */
 SERD_API
 void
@@ -633,7 +633,7 @@ serd_env_set_prefix_from_strings(SerdEnv*       env,
                                  const uint8_t* uri);
 
 /**
-   Qualify @c uri into a CURIE if possible.
+   Qualify `uri` into a CURIE if possible.
 */
 SERD_API
 bool
@@ -643,7 +643,7 @@ serd_env_qualify(const SerdEnv*  env,
                  SerdChunk*      suffix);
 
 /**
-   Expand @c curie.
+   Expand `curie`.
 */
 SERD_API
 SerdStatus
@@ -653,7 +653,7 @@ serd_env_expand(const SerdEnv*  env,
                 SerdChunk*      uri_suffix);
 
 /**
-   Expand @c node, which must be a CURIE or URI, to a full URI.
+   Expand `node`, which must be a CURIE or URI, to a full URI.
 */
 SERD_API
 SerdNode
@@ -661,7 +661,7 @@ serd_env_expand_node(const SerdEnv*  env,
                      const SerdNode* node);
 
 /**
-   Call @c func for each prefix defined in @c env.
+   Call `func` for each prefix defined in `env`.
 */
 SERD_API
 void
@@ -701,7 +701,7 @@ serd_reader_set_error_sink(SerdReader*   reader,
                            void*         handle);
 
 /**
-   Return the @c handle passed to @ref serd_reader_new.
+   Return the `handle` passed to serd_reader_new().
 */
 SERD_API
 void*
@@ -734,7 +734,7 @@ serd_reader_set_default_graph(SerdReader*     reader,
                               const SerdNode* graph);
 
 /**
-   Read a file at a given @c uri.
+   Read a file at a given `uri`.
 */
 SERD_API
 SerdStatus
@@ -776,7 +776,7 @@ SerdStatus
 serd_reader_end_stream(SerdReader* me);
 
 /**
-   Read @c file.
+   Read `file`.
 */
 SERD_API
 SerdStatus
@@ -785,14 +785,14 @@ serd_reader_read_file_handle(SerdReader*    reader,
                              const uint8_t* name);
 
 /**
-   Read @c utf8.
+   Read `utf8`.
 */
 SERD_API
 SerdStatus
 serd_reader_read_string(SerdReader* me, const uint8_t* utf8);
 
 /**
-   Free @c reader.
+   Free `reader`.
 */
 SERD_API
 void
@@ -817,14 +817,14 @@ serd_writer_new(SerdSyntax     syntax,
                 void*          stream);
 
 /**
-   Free @c writer.
+   Free `writer`.
 */
 SERD_API
 void
 serd_writer_free(SerdWriter* writer);
 
 /**
-   Return the env used by @c writer.
+   Return the env used by `writer`.
 */
 SERD_API
 SerdEnv*
@@ -834,7 +834,7 @@ serd_writer_get_env(SerdWriter* writer);
    A convenience sink function for writing to a FILE*.
 
    This function can be used as a SerdSink when writing to a FILE*.  The
-   @c stream parameter must be a FILE* opened for writing.
+   `stream` parameter must be a FILE* opened for writing.
 */
 SERD_API
 size_t
@@ -844,7 +844,7 @@ serd_file_sink(const void* buf, size_t len, void* stream);
    A convenience sink function for writing to a string.
 
    This function can be used as a SerdSink to write to a SerdChunk which is
-   resized as necessary with realloc().  The @c stream parameter must point to
+   resized as necessary with realloc().  The `stream` parameter must point to
    an initialized SerdChunk.  When the write is finished, the string should be
    retrieved with serd_chunk_sink_finish().
 */