From 87c1c0a6f46d4513751d998dacd1da7eee981e17 Mon Sep 17 00:00:00 2001
From: David Robillard <d@drobilla.net>
Date: Wed, 19 Jan 2011 19:27:49 +0000
Subject: Add documentation.

git-svn-id: http://svn.drobilla.net/serd/trunk@4 490d8e77-9747-427b-9fa3-0b8f29cee8a0
---
 serd/serd.h | 60 +++++++++++++++++++++++++++++++++++++++++++++++-------------
 1 file changed, 47 insertions(+), 13 deletions(-)

(limited to 'serd/serd.h')

diff --git a/serd/serd.h b/serd/serd.h
index 0e5d3029..d3d2b03d 100644
--- a/serd/serd.h
+++ b/serd/serd.h
@@ -40,49 +40,65 @@
 	#define SERD_API
 #endif
 
+/* @file
+ * Public Serd API.
+ */
+
+/** @defgroup serd Serd
+ * @brief A lightweight RDF Serialisation Library.
+ * @{
+ */
+
+/** RDF syntax */
 typedef enum {
 	SERD_TURTLE   = 1,
 	SERD_NTRIPLES = 2
 } SerdSyntax;
 
+/** Type of RDF node. */
+typedef enum {
+	BLANK   = 1,
+	URI     = 2,
+	QNAME   = 3,
+	LITERAL = 4
+} SerdNodeType;
+
 
-/** @defgroup string Measured UTF-8 string
+/** @name String
  * @{
  */
 
+/** Measured UTF-8 string. */
 typedef struct {
 	size_t  n_bytes;
 	size_t  n_chars;
 	uint8_t buf[];
 } SerdString;
 
+/** Create a new UTF-8 string from @a utf8. */
 SERD_API
 SerdString*
 serd_string_new(const uint8_t* utf8);
 
+/** Copy @a string. */
 SERD_API
 SerdString*
-serd_string_copy(const SerdString* s);
-
-typedef enum {
-	BLANK   = 1,
-	URI     = 2,
-	QNAME   = 3,
-	LITERAL = 4
-} SerdNodeType;
+serd_string_copy(const SerdString* string);
 
 /** @} */
 
-    
-/** @defgroup uri Parsed URI
+
+/** @name URIs
  * @{
  */
 
+/** Range of memory. */
 typedef struct {
 	const uint8_t* buf;
 	size_t         len;
 } SerdRange;
 
+/** Parsed URI. */
 typedef struct {
 	SerdRange scheme;
 	SerdRange authority;
@@ -93,22 +109,27 @@ typedef struct {
 	bool      base_uri_has_authority;
 } SerdURI;
 
+/** Return true iff @a utf8 is a relative URI string. */
 SERD_API
 bool
 serd_uri_string_is_relative(const uint8_t* utf8);
 
+/** Parse @a utf8, writing result to @a out. */
 SERD_API
 bool
 serd_uri_parse(const uint8_t* utf8, SerdURI* out);
 
+/** Resolve @a uri relative to @a base, writing result to @a out. */
 SERD_API
 bool
 serd_uri_resolve(const SerdURI* uri, const SerdURI* base, SerdURI* out);
 
+/** Write @a uri to @a file. */
 SERD_API
 bool
 serd_uri_write(const SerdURI* uri, FILE* file);
 
+/** Serialise @a uri to a string. */
 SERD_API
 SerdString*
 serd_uri_serialise(const SerdURI* uri,
@@ -117,19 +138,23 @@ serd_uri_serialise(const SerdURI* uri,
 /** @} */
 
 
-/** @defgroup reader Reader for RDF syntax
+/** @name Reader
  * @{
  */
 
+/** Reader. */
 typedef struct SerdReaderImpl* SerdReader;
 
+/** Handler for base URI changes. */
 typedef bool (*SerdBaseHandler)(void*             handle,
                                 const SerdString* uri);
 
+/** Handler for namespace definitions. */
 typedef bool (*SerdPrefixHandler)(void*             handle,
                                   const SerdString* name,
                                   const SerdString* uri);
 
+/** Handler for statements. */
 typedef bool (*SerdStatementHandler)(void*             handle,
                                      const SerdString* graph,
                                      const SerdString* subject,
@@ -141,6 +166,7 @@ typedef bool (*SerdStatementHandler)(void*             handle,
                                      const SerdString* object_lang,
                                      const SerdString* object_datatype);
 
+/** Create a new RDF reader. */
 SERD_API
 SerdReader
 serd_reader_new(SerdSyntax           syntax,
@@ -149,12 +175,14 @@ serd_reader_new(SerdSyntax           syntax,
                 SerdPrefixHandler    prefix_handler,
                 SerdStatementHandler statement_handler);
 
+/** Read @a file. */
 SERD_API
 bool
 serd_reader_read_file(SerdReader     reader,
                       FILE*          file,
                       const uint8_t* name);
 
+/** Free @a reader. */
 SERD_API
 void
 serd_reader_free(SerdReader reader);
@@ -162,26 +190,30 @@ serd_reader_free(SerdReader reader);
 /** @} */
 
 
-/** @defgroup namespaces Namespaces (prefixes for CURIEs)
+/** @name Namespaces
  * @{
  */
 
 typedef struct SerdNamespacesImpl* SerdNamespaces;
 
+/** Create a new namespaces dictionary. */
 SERD_API
 SerdNamespaces
 serd_namespaces_new();
 
+/** Free @a ns. */
 SERD_API
 void
 serd_namespaces_free(SerdNamespaces ns);
 
+/** Add namespace @a uri to @a ns using prefix @a name. */
 SERD_API
 void
 serd_namespaces_add(SerdNamespaces    ns,
                     const SerdString* name,
                     const SerdString* uri);
 
+/** Expand @a qname. */
 SERD_API
 bool
 serd_namespaces_expand(SerdNamespaces     ns,
@@ -191,4 +223,6 @@ serd_namespaces_expand(SerdNamespaces     ns,
 
 /** @} */
 
+/** @} */
+
 #endif /* SERD_SERD_H */
-- 
cgit v1.2.1