diff options
Diffstat (limited to 'include/sratom/sratom.h')
| -rw-r--r-- | include/sratom/sratom.h | 54 |
1 files changed, 23 insertions, 31 deletions
diff --git a/include/sratom/sratom.h b/include/sratom/sratom.h index 26966ee..077adff 100644 --- a/include/sratom/sratom.h +++ b/include/sratom/sratom.h @@ -14,9 +14,7 @@ OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. */ -/** - @file sratom.h API for Sratom, an LV2 Atom RDF serialisation library. -*/ +/// @file sratom.h Public API for Sratom #ifndef SRATOM_SRATOM_H #define SRATOM_SRATOM_H @@ -45,16 +43,12 @@ extern "C" { #endif /** - @defgroup sratom Sratom - - A library for serialising LV2 Atoms. - + @defgroup sratom Sratom C API + This is the public C API of Sratom. @{ */ -/** - Atom serialiser. -*/ +/// Atom serializer typedef struct SratomImpl Sratom; /** @@ -68,30 +62,26 @@ typedef struct SratomImpl Sratom; blank node IDs may be added in the future. */ typedef enum { - /** - Read blank nodes as Objects, and named resources as URIs. - */ + /// Read blank nodes as Objects, and named resources as URIs SRATOM_OBJECT_MODE_BLANK, /** - Read blank nodes and the main subject as Objects, and any other named - resources as URIs. The "main subject" is the subject parameter passed - to sratom_read(); if this is a resource it will be read as an Object, - but all other named resources encountered will be read as URIs. + Read blank nodes and the main subject as Objects. + + Any other named resources are read as URIs. The "main subject" is the + subject parameter passed to sratom_read(); if this is a resource it will + be read as an Object, but all other named resources encountered will be + read as URIs. */ SRATOM_OBJECT_MODE_BLANK_SUBJECT } SratomObjectMode; -/** - Create a new Atom serialiser. -*/ +/// Create a new Atom serializer SRATOM_API Sratom* sratom_new(LV2_URID_Map* map); -/** - Free an Atom serialisation. -*/ +/// Free an Atom serializer SRATOM_API void sratom_free(Sratom* sratom); @@ -130,16 +120,16 @@ SRATOM_API void sratom_set_pretty_numbers(Sratom* sratom, bool pretty_numbers); -/** - Configure how resources will be read to form LV2 Objects. -*/ +/// Configure how resources will be read to form LV2 Objects SRATOM_API void sratom_set_object_mode(Sratom* sratom, SratomObjectMode object_mode); /** Write an Atom to RDF. - The serialised atom is written to the sink set by sratom_set_sink(). + + The serialized atom is written to the sink set by sratom_set_sink(). + @return 0 on success, or a non-zero error code otherwise. */ SRATOM_API @@ -155,6 +145,7 @@ sratom_write(Sratom* sratom, /** Read an Atom from RDF. + The resulting atom will be written to `forge`. */ SRATOM_API @@ -166,7 +157,8 @@ sratom_read(Sratom* sratom, const SordNode* node); /** - Serialise an Atom to a Turtle string. + Serialize an Atom to a Turtle string. + The returned string must be free()'d by the caller. */ SRATOM_API @@ -182,6 +174,7 @@ sratom_to_turtle(Sratom* sratom, /** Read an Atom from a Turtle string. + The returned atom must be free()'d by the caller. */ SRATOM_API @@ -194,6 +187,7 @@ sratom_from_turtle(Sratom* sratom, /** A convenient resizing sink for LV2_Atom_Forge. + The handle must point to an initialized SerdChunk. */ SRATOM_API @@ -202,9 +196,7 @@ sratom_forge_sink(LV2_Atom_Forge_Sink_Handle handle, const void* buf, uint32_t size); -/** - The corresponding deref function for sratom_forge_sink. -*/ +/// The corresponding deref function for sratom_forge_sink SRATOM_API LV2_Atom* sratom_forge_deref(LV2_Atom_Forge_Sink_Handle handle, LV2_Atom_Forge_Ref ref); |