From 0bca3b5c25e278e92ce9f99e79151c3a02a97ed1 Mon Sep 17 00:00:00 2001 From: David Robillard Date: Tue, 14 Jul 2020 00:55:21 +0200 Subject: WIP: Improve documentation --- serd/serd.h | 96 +++++++++++++++++++++++++++++++++++++------------------------ 1 file changed, 58 insertions(+), 38 deletions(-) diff --git a/serd/serd.h b/serd/serd.h index a43acbca..04decb82 100644 --- a/serd/serd.h +++ b/serd/serd.h @@ -73,19 +73,19 @@ typedef struct SerdStatementImpl SerdStatement; /// The origin of a statement in a document typedef struct SerdCursorImpl SerdCursor; -/// Lexical environment for relative URIs or CURIEs (base URI and namespaces) +/// Lexical environment for abbreviating and expanding URIs typedef struct SerdEnvImpl SerdEnv; /// An indexed set of statements typedef struct SerdModelImpl SerdModel; -/// Model Iterator +/// An iterator that points to a statement in a model typedef struct SerdIterImpl SerdIter; -/// Model Range +/// A range of statements in a model typedef struct SerdRangeImpl SerdRange; -/// Streaming parser that reads a text stream and writes to a statement sink +/// Streaming parser that reads a text stream and writes to a sink typedef struct SerdReaderImpl SerdReader; /// Streaming serialiser that writes a text stream as statements are pushed @@ -136,7 +136,7 @@ typedef enum { /// Bitwise OR of SerdStatementFlag values typedef uint32_t SerdStatementFlags; -/// Flags that control style for a model serialisation +/// Flags that control the style of a model serialisation typedef enum { SERD_NO_INLINE_OBJECTS = 1 << 0 ///< Disable object inlining } SerdSerialisationFlag; @@ -145,13 +145,16 @@ typedef enum { typedef uint32_t SerdSerialisationFlags; /** - Type of a syntactic RDF node + Type of a 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 (by URI or CURIE) and two ways to refer to a blank - (by ID or anonymously). Anonymous (inline) blank nodes are expressed using - SerdStatementFlags rather than this type. + An RDF node, in the abstract sense, can be either a resource, literal, or a + blank. This type is more precise, because syntactically there are two ways + to refer to a resource (by URI or CURIE). Serd also has support for + variables nodes to support some features, which are not RDF nodes. + + There are also two ways to refer to a blank node in syntax (by ID or + anonymously), but this is handled by statement flags rather than distinct + node types. */ typedef enum { /** @@ -209,7 +212,7 @@ typedef enum { /// Bitwise OR of SerdNodeFlag values typedef uint32_t SerdNodeFlags; -/// Field in a statement +/// Index of a statement in a field typedef enum { SERD_SUBJECT = 0, ///< Subject SERD_PREDICATE = 1, ///< Predicate ("key") @@ -217,7 +220,7 @@ typedef enum { SERD_GRAPH = 3 ///< Graph ("context") } SerdField; -/// Indexing option +/// Flags that control model storage and indexing typedef enum { SERD_INDEX_SPO = 1, ///< Subject, Predicate, Object SERD_INDEX_SOP = 1 << 1, ///< Subject, Object, Predicate @@ -263,7 +266,7 @@ typedef struct { SerdStringView fragment; ///< Fragment } SerdURI; -/// Reader options +/// Reader support options typedef enum { SERD_READ_LAX = 1 << 0, ///< Tolerate invalid input where possible SERD_READ_VARIABLES = 1 << 1, ///< Support variable nodes @@ -276,10 +279,9 @@ typedef uint32_t SerdReaderFlags; /** Writer 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 - for some syntaxes (e.g. NTriples does not support abbreviation and is - always ASCII). + These flags allow more precise control of writer output style. Note that + some options are only supported for some syntaxes, for example, NTriples + does not support abbreviation and is always ASCII. */ typedef enum { SERD_WRITE_ASCII = 1 << 0, ///< Escape all non-ASCII characters @@ -1049,11 +1051,11 @@ typedef struct { /** An event in a data stream - Streams of data are represented as an ordered series of events. Events - represent everything that can occur in an RDF document, and are used to plumb - together different components. For example, when parsing a document, a - reader emits a stream of events which can be sent to a writer to serialise a - document, or to an inserter to build a model in memory. + Streams of data are represented as a series of events. Events represent + everything that can occur in an RDF document, and are used to plumb together + different components. For example, when parsing a document, a reader emits + a stream of events which can be sent to a writer to serialise a document, or + to an inserter to build a model in memory. */ typedef union { SerdEventType type; ///< Event type (always set) @@ -1246,7 +1248,13 @@ SERD_API SerdStatus serd_env_set_base_uri(SerdEnv* env, const SerdNode* uri); -/// Set a namespace prefix +/** + Set a namespace prefix + + A namespace prefix is used to expand CURIE nodes, for example, with the + prefix "xsd" set to "http://www.w3.org/2001/XMLSchema#", "xsd:decimal" will + expand to "http://www.w3.org/2001/XMLSchema#decimal". +*/ SERD_API SerdStatus serd_env_set_prefix(SerdEnv* env, const SerdNode* name, const SerdNode* uri); @@ -1261,7 +1269,8 @@ serd_env_set_prefix_from_strings(SerdEnv* env, /** Qualify `uri` into a CURIE if possible - Returns null if `node` can not be qualified. + Returns null if `uri` can not be qualified (usually because no corresponding + prefix is defined). */ SERD_API SerdNode* @@ -1270,7 +1279,9 @@ serd_env_qualify(const SerdEnv* env, const SerdNode* uri); /** Expand `node`, transforming CURIEs and URI references into absolute URIs. - If `node` is a literal, its datatype is expanded if necessary. + If `node` is a relative URI reference, it is expanded to a full URI if + possible. If `node` is a literal, its datatype is expanded if necessary. + If `node` is a CURIE, it is expanded to a full URI if possible. For simple nodes that do not require expansion, a copy is returned. Null is returned if `node` is/contains a CURIE or relative URI that can not be @@ -1406,11 +1417,11 @@ serd_reader_new(SerdWorld* world, /** 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. + This is useful when multiple files are to be parsed into the same output (a + model or a file). 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 @@ -1447,8 +1458,7 @@ serd_reader_read_document(SerdReader* reader); /** Finish reading from the source - This will close the open file, if applicable, and ensure the reader has - processed all input. + This should be called before starting to read from another source. */ SERD_API SerdStatus @@ -1515,13 +1525,18 @@ SERD_API char* serd_buffer_sink_finish(SerdBuffer* stream); -/// Set a prefix to be removed from matching blank node identifiers +/** + Set a prefix to be removed from matching blank node identifiers + + This is the counterpart to serd_reader_add_blank_prefix() which can be used + to "undo" added prefixes. +*/ SERD_API void serd_writer_chop_blank_prefix(SerdWriter* writer, const char* prefix); /** - Set the current output base URI (and emit directive if applicable) + Set the current output base URI, and emit a directive if applicable Note this function can be safely casted to SerdBaseSink. */ @@ -1543,7 +1558,12 @@ SERD_API SerdStatus serd_writer_set_root_uri(SerdWriter* writer, const SerdNode* uri); -/// Finish a write +/** + Finish a write + + This flushes any pending output, for example terminating punctuation, so + that the output is a complete document. +*/ SERD_API SerdStatus serd_writer_finish(SerdWriter* writer); @@ -1912,8 +1932,8 @@ serd_statement_equals(const SerdStatement* a, const SerdStatement* b); /** Return true iff `statement` matches the given pattern - The matching rules are the same used for querying: nodes match if they are - equivalent, and NULL acts as a wildcard that matches any node. + Nodes match if they are equivalent, or if one of them is NULL. The + statement matches if every node matches. */ SERD_API bool -- cgit v1.2.1