Switch to standard Javadoc/Doxygen style comments without leading asterisks.

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

1 files changed, 296 insertions, 154 deletions

diff --git a/serd/serd.h b/serd/serd.h
index 9409e782..974d0c47 100644
--- a/serd/serd.h
+++ b/serd/serd.h
@@ -15,9 +15,9 @@
  * along with this program. If not, see <http://www.gnu.org/licenses/>.
  */
 
-/** @file
- * Public Serd API.
- */
+/**
+   @file serd.h Public Serd API.
+*/
 
 #ifndef SERD_SERD_H
 #define SERD_SERD_H
@@ -48,196 +48,299 @@
 extern "C" {
 #endif
 
-/** @defgroup serd Serd
- * A lightweight RDF syntax library.
- * @{
- */
-
-typedef struct SerdEnvImpl*    SerdEnv;    /**< Namespace prefixes. */
-typedef struct SerdReaderImpl* SerdReader; /**< RDF reader. */
-typedef struct SerdWriterImpl* SerdWriter; /**< RDF writer. */
-
-/** RDF syntax */
+/**
+   @defgroup serd Serd
+   A lightweight RDF syntax library.
+   @{
+*/
+
+/**
+   Namespace prefixes.
+
+   A SerdEnv represents a set of namespace prefixes, and is used to resolve
+   CURIEs to full URIs.
+*/
+typedef struct SerdEnvImpl* SerdEnv;
+
+/**
+   RDF reader.
+
+   A SerdReader parses RDF by reading some syntax and calling user-provided
+   sink functions as input is read (much like an XML SAX parser).
+*/
+typedef struct SerdReaderImpl* SerdReader;
+
+/**
+   RDF writer.
+
+   A SerdWriter 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.
+*/
+typedef struct SerdWriterImpl* SerdWriter;
+
+/**
+   RDF syntax type.
+*/
 typedef enum {
-	SERD_TURTLE   = 1,  ///< <http://www.w3.org/TeamSubmission/turtle/>
-	SERD_NTRIPLES = 2   ///< <http://www.w3.org/TR/rdf-testcases/#ntriples>
+	/**
+	   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
 } SerdSyntax;
 
-/** 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 to refer to a resource (URI or CURIE), and two ways to refer to a
- * blank node (with a blank ID, or anonymously). Serd represents nodes as
- * an unquoted UTF-8 string "value" associated with a @ref SerdType,
- * which preserves syntactic information allowing for lossless abbreviation.
- * A non-abbreviating sink may simply consider @ref SERD_ANON_BEGIN and
- * @ref SERD_ANON equivalent to SERD_BLANK_ID.
- */
+/**
+   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 to
+   refer to both a resource (by URI or CURIE) and a blank (by ID or
+   anonymously).
+
+   Serd represents all nodes as an unquoted UTF-8 string "value" associated
+   with a @ref SerdType, which is precise enough to preserve the syntactic
+   information required for streaming abbreviation. A non-abbreviating sink may
+   simply consider @ref SERD_ANON_BEGIN and @ref SERD_ANON equivalent to
+   @ref SERD_BLANK_ID.
+*/
 typedef enum {
-	/** The type of a NULL node. */
+	/**
+	   The type of a nonexistent node.
+
+	   This type is occasionally useful, but is never emitted by the reader.
+	*/
 	SERD_NOTHING = 0,
 
-	/** Literal value. A literal optionally has either an associated language,
-	 * or an associated datatype (not both).
-	 */
+	/**
+	   Literal value.
+
+	   A literal optionally has either an associated language, or an associated
+	   datatype (not both).
+	*/
 	SERD_LITERAL = 1,
 
-	/** URI. Value is a valid URI string (either absolute or relative), which
-	 * is valid universally. See <http://tools.ietf.org/html/rfc3986>.
-	 */
+	/**
+	   URI (absolute or relative).
+
+	   Value is an unquoted URI string, which is either a relative reference
+	   with respect to the current base URI, or an absolute URI. A URI is an ID
+	   with universal scope.
+	   @see <a href="http://tools.ietf.org/html/rfc3986">RFC3986</a>.
+	*/
 	SERD_URI = 2,
 
-	/** CURIE, a shortened URI. Value is an unquoted UTF-8 CURIE string
-	 * relative to the current environment, e.g. "rdf:type", which is valid
-	 * only within this serialisation. See <http://www.w3.org/TR/curie>.
-	 */
+	/**
+	   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>
+	*/
 	SERD_CURIE = 3,
 
-	/** A blank node ID. Value is a blank node identifier (e.g. "blank3"),
-	 * which is valid only within this serialisation.
-	 * See <http://www.w3.org/TeamSubmission/turtle#nodeID>.
-	 */
+	/**
+	   A blank node ID.
+
+	   Value is a blank node ID, e.g. "id3", which is valid only in this
+	   serialisation.
+	   @see <a href="http://www.w3.org/TeamSubmission/turtle#nodeID">Turtle
+	   <tt>nodeID</tt></a>
+	*/
 	SERD_BLANK_ID = 4,
 
-	/** The first reference to an anonymous (inlined) blank node.
-	 * Value is identical to a @ref SERD_BLANK_ID value.
-	 */
+	/**
+	   The first reference to an anonymous (inlined) blank node.
+	   
+	   Value is identical to a @ref SERD_BLANK_ID value (i.e. this type may be
+	   safely considered equivalent to @ref SERD_BLANK_ID).
+	*/
 	SERD_ANON_BEGIN = 5,
 
-	/** An anonymous blank node.
-	 * Value is identical to a @ref SERD_BLANK_ID value.
-	 */
+	/**
+	   An anonymous blank node.
+
+	   Value is identical to a @ref SERD_BLANK_ID value (i.e. this type may be
+	   safely considered equivalent to @ref SERD_BLANK_ID).
+	*/
 	SERD_ANON = 6
 } SerdType;
 
-/** @name SerdURI
- * A parsed URI.
- * @{
- */
+/**
+   @name SerdURI
+   @{
+*/
 
-/** An unterminated string fragment. */
+/**
+   An unterminated string fragment.
+*/
 typedef struct {
-	const uint8_t* buf;  ///< Start of chunk
-	size_t         len;  ///< Length of chunk in bytes
+	const uint8_t* buf;  /**< Start of chunk */
+	size_t         len;  /**< Length of chunk in bytes */
 } SerdChunk;
 
-/** A parsed URI.
- * This struct directly refers to chunks 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.
- */
+/**
+   A parsed URI.
+   
+   This struct directly refers to chunks 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 {
-	SerdChunk scheme;     ///< Scheme
-	SerdChunk authority;  ///< Authority
-	SerdChunk path_base;  ///< Path prefix if relative
-	SerdChunk path;       ///< Path suffix
-	SerdChunk query;      ///< Query
-	SerdChunk fragment;   ///< Fragment
+	SerdChunk scheme;     /**< Scheme */
+	SerdChunk authority;  /**< Authority */
+	SerdChunk path_base;  /**< Path prefix if relative */
+	SerdChunk path;       /**< Path suffix */
+	SerdChunk query;      /**< Query */
+	SerdChunk fragment;   /**< Fragment */
 } SerdURI;
 
 static const SerdURI SERD_URI_NULL = {{0,0},{0,0},{0,0},{0,0},{0,0},{0,0}};
 
-/** Return true iff @a utf8 starts with a valid URI scheme. */
+/**
+   Return true iff @a utf8 starts with a valid URI scheme.
+*/
 SERD_API
 bool
 serd_uri_string_has_scheme(const uint8_t* utf8);
 
-/** Parse @a utf8, writing result to @a out. */
+/**
+   Parse @a utf8, writing result to @a out.
+*/
 SERD_API
 bool
 serd_uri_parse(const uint8_t* utf8, SerdURI* out);
 
-/** Set @a out to @a uri resolved against @a base. */
+/**
+   Set @a out to @a uri resolved against @a base.
+*/
 SERD_API
 void
 serd_uri_resolve(const SerdURI* uri, const SerdURI* base, SerdURI* out);
 
-/** Sink function for raw string output. */
+/**
+   Sink function for raw string output.
+*/
 typedef size_t (*SerdSink)(const void* buf, size_t len, void* stream);
 
-/** Serialise @a uri with a series of calls to @a sink. */
+/**
+   Serialise @a uri with a series of calls to @a sink.
+*/
 SERD_API
 size_t
 serd_uri_serialise(const SerdURI* uri, SerdSink sink, void* stream);
 
-/** @} */
-/** @name SerdNode
- * @brief An RDF node.
- * @{
- */
+/**
+   @}
+   @name SerdNode
+   @{
+*/
 
-/** A syntactic RDF node. */
+/**
+   A syntactic RDF node.
+*/
 typedef struct {
 	SerdType       type;
-	size_t         n_bytes;  ///< Size in bytes including trailing null byte
-	size_t         n_chars;  ///< Length in characters
-	const uint8_t* buf;      ///< Buffer
+	size_t         n_bytes;  /**< Size in bytes (including null) */
+	size_t         n_chars;  /**< Length in characters */
+	const uint8_t* buf;      /**< Buffer */
 } SerdNode;
 
 static const SerdNode SERD_NODE_NULL = { SERD_NOTHING, 0, 0, 0 };
 
-/** Make a (shallow) node from @a str.
- * This measures, but does not copy, @a str.  No memory is allocated.
- */
+/**
+   Make a (shallow) node from @a str.
+   
+   This measures, but does not copy, @a str.  No memory is allocated.
+*/
 SERD_API
 SerdNode
 serd_node_from_string(SerdType type, const uint8_t* str);
 
-/** Make a deep copy of @a node.
- * @return a node that the caller must free with @ref serd_node_free.
- */
+/**
+   Make a deep copy of @a node.
+   
+   @return a node that the caller must free with @ref serd_node_free.
+*/
 SERD_API
 SerdNode
 serd_node_copy(const SerdNode* node);
 
-/** Simple wrapper for serd_node_new_uri to resolve a URI node. */
+/**
+   Simple wrapper for serd_node_new_uri to resolve a URI node.
+*/
 SERD_API
 SerdNode
 serd_node_new_uri_from_node(const SerdNode* uri_node,
                             const SerdURI*  base,
                             SerdURI*        out);
 
-/** Simple wrapper for serd_node_new_uri to resolve a URI string. */
+/**
+   Simple wrapper for serd_node_new_uri to resolve a URI string.
+*/
 SERD_API
 SerdNode
 serd_node_new_uri_from_string(const uint8_t* str,
                               const SerdURI* base,
                               SerdURI*       out);
 
-/** Create a new node by serialising @a uri into a new string.
- * @param uri The URI to parse and serialise.
- * @param base Base URI to resolve @a uri against (or NULL for no resolution).
- * @param out (Output) set to the parsing of the new URI (i.e. points only to
- *        memory owned by the new returned node).
- */
+/**
+   Create a new node by serialising @a uri into a new string.
+   
+   @param uri The URI to parse and serialise.
+   @param base Base URI to resolve @a uri against (or NULL for no resolution).
+   @param out (Output) set to the parsing of the new URI (i.e. points only to
+   memory owned by the new returned node).
+*/
 SERD_API
 SerdNode
 serd_node_new_uri(const SerdURI* uri, const SerdURI* base, SerdURI* out);
 
-/** Free any data owned by @a node.
- * Note that if @a node is itself dynamically allocated (which is not the case
- * for nodes created internally by serd), it will not be freed.
- */
+/**
+   Free any data owned by @a node.
+   
+   Note that if @a node is itself dynamically allocated (which is not the case
+   for nodes created internally by serd), it will not be freed.
+*/
 SERD_API
 void
 serd_node_free(SerdNode* node);
 
-/** @} */
-/** @name SerdHandlers
- * @brief Event handlers (user-provided worker functions).
- * @{
- */
+/**
+   @}
+   @name Handlers
+   @{
+*/
 
-/** Sink for base URI changes. */
+/**
+   Sink for base URI changes.
+
+   Called whenever the base URI of the serialisation changes.
+*/
 typedef bool (*SerdBaseSink)(void*           handle,
                              const SerdNode* uri);
 
-/** Sink for namespace definitions. */
+/**
+   Sink for namespace definitions.
+
+   Called whenever a prefix is defined in the serialisation.
+*/
 typedef bool (*SerdPrefixSink)(void*           handle,
                                const SerdNode* name,
                                const SerdNode* uri);
 
-/** Sink for statements. */
+/**
+   Sink for statements.
+
+   Called for every RDF statement in the serialisation.
+*/
 typedef bool (*SerdStatementSink)(void*           handle,
                                   const SerdNode* graph,
                                   const SerdNode* subject,
@@ -246,30 +349,48 @@ typedef bool (*SerdStatementSink)(void*           handle,
                                   const SerdNode* object_datatype,
                                   const SerdNode* object_lang);
 
-/** @} */
-/** @name SerdEnv
- * @brief An environment (a prefix => URI dictionary).
- * @{
- */
+/**
+   Sink for anonymous node end markers.
+   
+   This is called to indicate that the anonymous node with the given
+   @a value will no longer be referred to by any future statements
+   (i.e. the anonymous serialisation of the node is finished).
+*/
+typedef bool (*SerdEndSink)(void*           handle,
+                            const SerdNode* node);
 
-/** Create a new environment. */
+/**
+   @}
+   @name SerdEnv
+   @{
+*/
+
+/**
+   Create a new environment.
+*/
 SERD_API
 SerdEnv
 serd_env_new();
 
-/** Free @a ns. */
+/**
+   Free @a ns.
+*/
 SERD_API
 void
 serd_env_free(SerdEnv env);
 
-/** Add namespace @a uri to @a ns using prefix @a name. */
+/**
+   Add namespace @a uri to @a ns using prefix @a name.
+*/
 SERD_API
 void
 serd_env_add(SerdEnv         env,
              const SerdNode* name,
              const SerdNode* uri);
 
-/** Qualify @a into a CURIE if possible. */
+/**
+   Qualify @a into a CURIE if possible.
+*/
 SERD_API
 bool
 serd_env_qualify(const SerdEnv   env,
@@ -277,7 +398,9 @@ serd_env_qualify(const SerdEnv   env,
                  SerdNode*       prefix,
                  SerdChunk*      suffix);
 
-/** Expand @a curie. */
+/**
+   Expand @a curie.
+*/
 SERD_API
 bool
 serd_env_expand(const SerdEnv   env,
@@ -285,28 +408,24 @@ serd_env_expand(const SerdEnv   env,
                 SerdChunk*      uri_prefix,
                 SerdChunk*      uri_suffix);
 
-/** Call @a func for each prefix defined in @a env. */
+/**
+   Call @a func for each prefix defined in @a env.
+*/
 SERD_API
 void
 serd_env_foreach(const SerdEnv  env,
                  SerdPrefixSink func,
                  void*          handle);
 
-/** @} */
-/** @name SerdReader
- * @brief Reader of RDF syntax.
- * @{
- */
+/**
+   @}
+   @name SerdReader
+   @{
+*/
 
-/** Sink for anonymous node end markers.
- * This is called to indicate that the anonymous node with the given
- * @a value will no longer be referred to by any future statements
- * (i.e. the anonymous serialisation of the node is finished).
- */
-typedef bool (*SerdEndSink)(void*           handle,
-                            const SerdNode* node);
-
-/** Create a new RDF reader. */
+/**
+   Create a new RDF reader.
+*/
 SERD_API
 SerdReader
 serd_reader_new(SerdSyntax        syntax,
@@ -316,40 +435,48 @@ serd_reader_new(SerdSyntax        syntax,
                 SerdStatementSink statement_sink,
                 SerdEndSink       end_sink);
 
-/** 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
- * could cause conflicts where two non-equivalent blank nodes are merged,
- * resulting in corrupt data.  By setting a unique blank node prefix for
- * each parsed file, this can be avoided, while preserving blank node names.
- */
+/**
+   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
+   could cause conflicts where two non-equivalent blank nodes are merged,
+   resulting in corrupt data.  By setting a unique blank node prefix for each
+   parsed file, this can be avoided, while preserving blank node names.
+*/
 SERD_API
 void
 serd_reader_set_blank_prefix(SerdReader     reader,
                              const uint8_t* prefix);
 
-/** Read @a file. */
+/**
+   Read @a file.
+*/
 SERD_API
 bool
 serd_reader_read_file(SerdReader     reader,
                       FILE*          file,
                       const uint8_t* name);
 
-/** Read @a utf8. */
+/**
+   Read @a utf8.
+*/
 SERD_API
 bool
 serd_reader_read_string(SerdReader me, const uint8_t* utf8);
 
-/** Free @a reader. */
+/**
+   Free @a reader.
+*/
 SERD_API
 void
 serd_reader_free(SerdReader reader);
 
-/** @} */
-/** @name SerdWriter
- * @brief Writer of RDF syntax.
- * @{
- */
+/**
+   @}
+   @name SerdWriter
+   @{
+*/
 
 typedef enum {
 	SERD_STYLE_ABBREVIATED = 1,      /**< Abbreviate triples when possible. */
@@ -358,7 +485,9 @@ typedef enum {
 	SERD_STYLE_CURIED      = 1 << 3  /**< Shorted URIs into CURIEs. */
 } SerdStyle;
 
-/** Create a new RDF writer. */
+/**
+   Create a new RDF writer.
+*/
 SERD_API
 SerdWriter
 serd_writer_new(SerdSyntax     syntax,
@@ -368,25 +497,33 @@ serd_writer_new(SerdSyntax     syntax,
                 SerdSink       sink,
                 void*          stream);
 
-/** Free @a writer. */
+/**
+   Free @a writer.
+*/
 SERD_API
 void
 serd_writer_free(SerdWriter writer);
 
-/** Set the current output base URI (and emit directive if applicable). */
+/**
+   Set the current output base URI (and emit directive if applicable).
+*/
 SERD_API
 void
 serd_writer_set_base_uri(SerdWriter     writer,
                          const SerdURI* uri);
 
-/** Set a namespace prefix (and emit directive if applicable). */
+/**
+   Set a namespace prefix (and emit directive if applicable).
+*/
 SERD_API
 bool
 serd_writer_set_prefix(SerdWriter      writer,
                        const SerdNode* name,
                        const SerdNode* uri);
 
-/** Write a statement. */
+/**
+   Write a statement.
+*/
 SERD_API
 bool
 serd_writer_write_statement(SerdWriter      writer,
@@ -397,20 +534,25 @@ serd_writer_write_statement(SerdWriter      writer,
                             const SerdNode* object_datatype,
                             const SerdNode* object_lang);
 
-/** Mark the end of an anonymous node's description. */
+/**
+   Mark the end of an anonymous node's description.
+*/
 SERD_API
 bool
 serd_writer_end_anon(SerdWriter      writer,
                      const SerdNode* node);
 
-/** Finish a write. */
+/**
+   Finish a write.
+*/
 SERD_API
 void
 serd_writer_finish(SerdWriter writer);
 
-/** @} */
-
-/** @} */
+/**
+   @}
+   @}
+*/
 
 #ifdef __cplusplus
 } /* extern "C" */