From f0c50e7461641d060c783e1f0fb1b74b3c175054 Mon Sep 17 00:00:00 2001
From: David Robillard <d@drobilla.net>
Date: Thu, 20 Jan 2011 18:12:59 +0000
Subject: Flesh out documentation.

git-svn-id: http://svn.drobilla.net/serd/trunk@12 490d8e77-9747-427b-9fa3-0b8f29cee8a0
---
 serd/serd.h      | 39 +++++++++++++++++++++------------------
 src/namespaces.c |  4 ++--
 src/serdi.c      |  2 +-
 src/uri.c        |  2 +-
 src/write.c      |  4 ++--
 5 files changed, 27 insertions(+), 24 deletions(-)

diff --git a/serd/serd.h b/serd/serd.h
index 3c39e593..98aea4b5 100644
--- a/serd/serd.h
+++ b/serd/serd.h
@@ -53,9 +53,8 @@ extern "C" {
  * @{
  */
 
-typedef struct SerdNamespacesImpl* SerdNamespaces;
-typedef struct SerdReaderImpl*     SerdReader;
-
+typedef struct SerdNamespacesImpl* SerdNamespaces;  ///< Set of namespaces
+typedef struct SerdReaderImpl*     SerdReader;      ///< RDF reader
 
 /** RDF syntax */
 typedef enum {
@@ -75,21 +74,24 @@ typedef enum {
  * @{
  */
 
-/* Range of memory. */
+/** A chunk of memory (non-terminated string). */
 typedef struct {
-	const uint8_t* buf;
-	size_t         len;
-} SerdRange;
-
-/* Parsed URI. */
+	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.
+ */
 typedef struct {
-	SerdRange scheme;     ///< Scheme
-	SerdRange authority;  ///< Authority
-	SerdRange path_base;  ///< Path prefix if relative
-	SerdRange path;       ///< Path suffix
-	SerdRange query;      ///< Query
-	SerdRange fragment;   ///< Fragment
-	bool      base_uri_has_authority;  ///< True iff base URI has authority
+	SerdChunk scheme;     ///< Scheme
+	SerdChunk authority;  ///< Authority
+	SerdChunk path_base;  ///< Path prefix if relative
+	SerdChunk path;       ///< Path suffix
+	SerdChunk query;      ///< Query
+	SerdChunk fragment;   ///< Fragment
 } SerdURI;
 
 /** Return true iff @a utf8 is a relative URI string. */
@@ -149,6 +151,7 @@ SerdString*
 serd_string_new_from_uri(const SerdURI* uri,
                          SerdURI*       out);
 
+/** Write a node to @a file. */
 SERD_API
 bool
 serd_write_node(FILE*             file,
@@ -237,8 +240,8 @@ SERD_API
 bool
 serd_namespaces_expand(SerdNamespaces     ns,
                        const SerdString*  qname,
-                       SerdRange*         uri_prefix,
-                       SerdRange*         uri_suffix);
+                       SerdChunk*         uri_prefix,
+                       SerdChunk*         uri_suffix);
 
 /** @} */
 
diff --git a/src/namespaces.c b/src/namespaces.c
index a2526a5d..b14d74c5 100644
--- a/src/namespaces.c
+++ b/src/namespaces.c
@@ -95,8 +95,8 @@ SERD_API
 bool
 serd_namespaces_expand(SerdNamespaces    ns,
                        const SerdString* qname,
-                       SerdRange*        uri_prefix,
-                       SerdRange*        uri_suffix)
+                       SerdChunk*        uri_prefix,
+                       SerdChunk*        uri_suffix)
 {
 	const uint8_t* colon = memchr((const char*)qname->buf, ':', qname->n_bytes);
 	if (!colon) {
diff --git a/src/serdi.c b/src/serdi.c
index 6b4e62b4..548f88e7 100644
--- a/src/serdi.c
+++ b/src/serdi.c
@@ -39,7 +39,7 @@ event_base(void*             handle,
 		return false;
 	}
 
-	SerdURI     base_uri = {{0,0},{0,0},{0,0},{0,0},{0,0},{0,0},false};
+	SerdURI     base_uri = {{0,0},{0,0},{0,0},{0,0},{0,0},{0,0}};
 	SerdString* base_uri_str;
 	if (!uri.scheme.len) {
 		// URI has no scheme (relative by definition), resolve
diff --git a/src/uri.c b/src/uri.c
index 5f7a405e..a7e7178c 100644
--- a/src/uri.c
+++ b/src/uri.c
@@ -93,7 +93,7 @@ SERD_API
 bool
 serd_uri_parse(const uint8_t* utf8, SerdURI* uri)
 {
-	static const SerdURI null_uri = {{0,0},{0,0},{0,0},{0,0},{0,0},{0,0},false};
+	static const SerdURI null_uri = {{0,0},{0,0},{0,0},{0,0},{0,0},{0,0}};
 	*uri = null_uri;
 	assert(uri->path_base.buf == NULL);
 	assert(uri->path_base.len == 0);
diff --git a/src/write.c b/src/write.c
index c2b92d78..633655d8 100644
--- a/src/write.c
+++ b/src/write.c
@@ -115,8 +115,8 @@ serd_write_node(FILE*             fd,
                 const SerdString* datatype,
                 const SerdString* lang)
 {
-	SerdRange uri_prefix;
-	SerdRange uri_suffix;
+	SerdChunk uri_prefix;
+	SerdChunk uri_suffix;
 	switch (type) {
 	case BLANK:
 		fwrite("_:", 1, 2, fd);
-- 
cgit v1.2.1