aboutsummaryrefslogtreecommitdiffstats
diff options
context:
space:
mode:
authorDavid Robillard <d@drobilla.net>2011-05-06 14:57:59 +0000
committerDavid Robillard <d@drobilla.net>2011-05-06 14:57:59 +0000
commit6bd8d39e12801d21fbf59da2da08602aab9eff32 (patch)
treed853b5a6ab3590ff18b18b7937b2f26313b8e2b4
parentb490ec05c2ecb3e3027da554fa0f53c1073a6c6e (diff)
downloadserd-6bd8d39e12801d21fbf59da2da08602aab9eff32.tar.gz
serd-6bd8d39e12801d21fbf59da2da08602aab9eff32.tar.bz2
serd-6bd8d39e12801d21fbf59da2da08602aab9eff32.zip
Improve documentation.
git-svn-id: http://svn.drobilla.net/serd/trunk@162 490d8e77-9747-427b-9fa3-0b8f29cee8a0
-rw-r--r--serd/serd.h47
1 files changed, 24 insertions, 23 deletions
diff --git a/serd/serd.h b/serd/serd.h
index 8bb2ca83..3fbe99e4 100644
--- a/serd/serd.h
+++ b/serd/serd.h
@@ -54,38 +54,39 @@ extern "C" {
*/
/**
- Environment (namespace prefixes).
+ Environment.
- A SerdEnv represents a set of namespace prefixes, and is used to resolve
- CURIEs to full URIs.
+ 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 in a
+ serialisation.
*/
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).
+ parses RDF by calling user-provided sink functions as input is consumed
+ (much like an XML SAX parser).
*/
typedef struct SerdReaderImpl SerdReader;
/**
Read state.
- This represents state (context) necessary for fully resolving URIs during a
- read (i.e. the base URI and namespace prefixes). It is implemented
- separately from SerdReader so the reader can avoid the overhead in cases
- where this information is unnecessary (e.g. streaming reserialisation).
+ This maintains the state necessary to fully resolve URIs during a read
+ (e.g. the base URI and prefixes). It is implemented separately from
+ SerdReader to avoid overhead in situations where this is unnecessary
+ (e.g. streaming re-serialisation).
*/
typedef struct SerdReadStateImpl SerdReadState;
/**
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.
+ 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;
@@ -121,15 +122,15 @@ typedef enum {
/**
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
+ 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
+ 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 {
@@ -152,8 +153,8 @@ typedef enum {
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.
+ 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,
@@ -170,7 +171,7 @@ typedef enum {
/**
A blank node ID.
- Value is a blank node ID, e.g. "id3", which is valid only in this
+ Value is a blank node ID, e.g. "id3", which is valid only within this
serialisation.
@see <a href="http://www.w3.org/TeamSubmission/turtle#nodeID">Turtle
<tt>nodeID</tt></a>
@@ -216,7 +217,7 @@ typedef struct {
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
+ memory itself. Thus, URIs can be parsed and/or resolved against a base URI
in-place without allocating memory.
*/
typedef struct {
@@ -232,7 +233,7 @@ typedef struct {
Syntax 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
+ values from this enumeration. Note that some options are only supported
for some syntaxes (e.g. NTriples does not support any options except
@ref SERD_STYLE_ASCII, which is required).
*/