Clean up documentation.

Improve object query function names.

6 files changed, 62 insertions, 63 deletions

diff --git a/lv2/lv2plug.in/ns/ext/atom/atom-test.c b/lv2/lv2plug.in/ns/ext/atom/atom-test.c
index c81f581..7375a17 100644
--- a/lv2/lv2plug.in/ns/ext/atom/atom-test.c
+++ b/lv2/lv2plug.in/ns/ext/atom/atom-test.c
@@ -309,7 +309,7 @@ main()
 		LV2_OBJECT_QUERY_END
 	};
 
-	unsigned n_matches = lv2_object_get((LV2_Atom_Object*)obj, q);
+	unsigned n_matches = lv2_object_query((LV2_Atom_Object*)obj, q);
 	for (int i = 0; i < 2; ++i) {
 		if (n_matches != n_props) {
 			return test_fail("Query failed, %u matches != %u\n",
@@ -342,22 +342,22 @@ main()
 			return test_fail("Bad match sequence\n");
 		}
 		memset(&matches, 0, sizeof(matches));
-		n_matches = lv2_object_getv((LV2_Atom_Object*)obj,
-		                            eg_one,     &matches.one,
-		                            eg_two,     &matches.two,
-		                            eg_three,   &matches.three,
-		                            eg_four,    &matches.four,
-		                            eg_true,    &matches.affirmative,
-		                            eg_false,   &matches.negative,
-		                            eg_path,    &matches.path,
-		                            eg_uri,     &matches.uri,
-		                            eg_urid,    &matches.urid,
-		                            eg_string,  &matches.string,
-		                            eg_literal, &matches.literal,
-		                            eg_tuple,   &matches.tuple,
-		                            eg_vector,  &matches.vector,
-		                            eg_seq,     &matches.seq,
-		                            0);
+		n_matches = lv2_object_get((LV2_Atom_Object*)obj,
+		                           eg_one,     &matches.one,
+		                           eg_two,     &matches.two,
+		                           eg_three,   &matches.three,
+		                           eg_four,    &matches.four,
+		                           eg_true,    &matches.affirmative,
+		                           eg_false,   &matches.negative,
+		                           eg_path,    &matches.path,
+		                           eg_uri,     &matches.uri,
+		                           eg_urid,    &matches.urid,
+		                           eg_string,  &matches.string,
+		                           eg_literal, &matches.literal,
+		                           eg_tuple,   &matches.tuple,
+		                           eg_vector,  &matches.vector,
+		                           eg_seq,     &matches.seq,
+		                           0);
 	}
 
 	printf("All tests passed.\n");
diff --git a/lv2/lv2plug.in/ns/ext/atom/atom.h b/lv2/lv2plug.in/ns/ext/atom/atom.h
index a8ec72d..791e18c 100644
--- a/lv2/lv2plug.in/ns/ext/atom/atom.h
+++ b/lv2/lv2plug.in/ns/ext/atom/atom.h
@@ -17,14 +17,14 @@
 /**
    @file atom.h C header for the LV2 Atom extension
    <http://lv2plug.in/ns/ext/atom>.
-
-   This header describes the binary layout of various types defined in the
-   atom extension.
 */
 
 #ifndef LV2_ATOM_H
 #define LV2_ATOM_H
 
+#include <stdint.h>
+#include <stddef.h>
+
 #define LV2_ATOM_URI "http://lv2plug.in/ns/ext/atom"
 
 #define LV2_ATOM__Atom          LV2_ATOM_URI "#Atom"
@@ -60,9 +60,6 @@
 
 #define LV2_ATOM_REFERENCE_TYPE 0
 
-#include <stdint.h>
-#include <stddef.h>
-
 #ifdef __cplusplus
 extern "C" {
 #endif
@@ -72,7 +69,7 @@ typedef char lv2_atom_assert_double_fits_in_64_bits[
 	((sizeof(double) <= sizeof(uint64_t)) * 2) - 1];
 
 /**
-   Return a pointer to the contents of a variable-sized atom.
+   Return a pointer to the contents of an Atom.
    @param type The type of the atom, e.g. LV2_Atom_String.
    @param atom A variable-sized atom.
 */
@@ -90,26 +87,26 @@ typedef struct {
 
 /** An atom:Int32 or atom:Bool.  May be cast to LV2_Atom. */
 typedef struct {
-	LV2_Atom atom;
-	int32_t  value;
+	LV2_Atom atom;   /**< Atom header. */
+	int32_t  value;  /**< Integer value. */
 } LV2_Atom_Int32;
 
 /** An atom:Int64.  May be cast to LV2_Atom. */
 typedef struct {
-	LV2_Atom atom;
-	int64_t  value;
+	LV2_Atom atom;   /**< Atom header. */
+	int64_t  value;  /**< Integer value. */
 } LV2_Atom_Int64;
 
 /** An atom:Float.  May be cast to LV2_Atom. */
 typedef struct {
-	LV2_Atom atom;
-	float    value;
+	LV2_Atom atom;   /**< Atom header. */
+	float    value;  /**< Floating point value. */
 } LV2_Atom_Float;
 
 /** An atom:Double.  May be cast to LV2_Atom. */
 typedef struct {
-	LV2_Atom atom;
-	double   value;
+	LV2_Atom atom;   /**< Atom header. */
+	double   value;  /**< Floating point value. */
 } LV2_Atom_Double;
 
 /** An atom:Bool.  May be cast to LV2_Atom. */
@@ -130,8 +127,8 @@ typedef struct {
 /** The complete header of an atom:Literal. */
 typedef struct {
 	LV2_Atom atom;      /**< Atom header. */
-	uint32_t datatype;  /**< The ID of the datatype of this literal. */
-	uint32_t lang;      /**< The ID of the language of this literal. */
+	uint32_t datatype;  /**< Datatype URID. */
+	uint32_t lang;      /**< Language URID. */
 	/* Contents (a null-terminated UTF-8 string) follow here. */
 } LV2_Atom_Literal;
 
@@ -167,8 +164,8 @@ typedef struct {
 
 /** The complete header of an atom:Object. */
 typedef struct {
-	LV2_Atom atom;  /**< Atom header. */
-	uint32_t id;    /**< URID for atom:Resource, or blank ID for atom:Blank. */
+	LV2_Atom atom;   /**< Atom header. */
+	uint32_t id;     /**< URID (atom:Resource) or blank ID (atom:Blank). */
 	uint32_t otype;  /**< Type URID (same as rdf:type, for fast dispatch). */
 	/* Contents (a series of property bodies) follow here. */
 } LV2_Atom_Object;
diff --git a/lv2/lv2plug.in/ns/ext/atom/atom.ttl b/lv2/lv2plug.in/ns/ext/atom/atom.ttl
index c3249ec..ce1aed2 100644
--- a/lv2/lv2plug.in/ns/ext/atom/atom.ttl
+++ b/lv2/lv2plug.in/ns/ext/atom/atom.ttl
@@ -30,8 +30,8 @@
 	rdfs:seeAlso <util.h> ,
 		<forge.h> ;
 	doap:release [
-		doap:revision "0.4" ;
-		doap:created "2012-02-07"
+		doap:revision "0.5" ;
+		doap:created "2012-02-18"
 	] ;
 	doap:maintainer [
 		a foaf:Person ;
@@ -523,4 +523,4 @@ atom:eventTransfer
 atom:Sequence.  The host must transfer each individual event to the recipient.
 The format of the received data is an LV2_Atom, there is no timestamp
 header.</p>
-""" .
\ No newline at end of file
+""" .
diff --git a/lv2/lv2plug.in/ns/ext/atom/forge.h b/lv2/lv2plug.in/ns/ext/atom/forge.h
index 52ba635..acfc6a8 100644
--- a/lv2/lv2plug.in/ns/ext/atom/forge.h
+++ b/lv2/lv2plug.in/ns/ext/atom/forge.h
@@ -17,20 +17,21 @@
 /**
    @file forge.h An API for constructing LV2 atoms.
 
-   This file provides a simple API which can be used to create complex nested
-   atoms by calling the provided functions to append atoms (or atom headers) in
-   the correct order.
+   This file provides an API for constructing Atoms which makes it relatively
+   simple to build nested atoms of arbitrary complexity without requiring
+   dynamic memory allocation.
 
-   The size of containers is automatically handled to any depth.  All functions
-   that start a container take a pointer to an uninitialised stack frame which
-   will be initialised and must be popped when the container is finished.
+   The API is based on successively appending the appropriate pieces to build a
+   complete Atom.  The size of containers is automatically updated.  Functions
+   that begin a container return (via their frame argument) a stack frame which
+   must be popped when the container is finished.
 
-   All output is written to a user-provided buffer, or sink function.  Thus,
-   this API can be used to create atoms on the stack, on the heap, in LV2 port
-   buffers, or in a ringbuffer.
+   All output is written to a user-provided buffer or sink function.  This
+   makes it popssible to create create atoms on the stack, on the heap, in LV2
+   port buffers, in a ringbuffer, or elsewhere, all using the same API.
 
    This entire API is realtime safe if used with a buffer or a realtime safe
-   sink, except lv2_atom_forge_init(), which is only realtime safe if the URI
+   sink, except lv2_atom_forge_init() which is only realtime safe if the URI
    map function is.
 
    Note these functions are all static inline, do not take their address.
diff --git a/lv2/lv2plug.in/ns/ext/atom/manifest.ttl b/lv2/lv2plug.in/ns/ext/atom/manifest.ttl
index 37f0f58..9730981 100644
--- a/lv2/lv2plug.in/ns/ext/atom/manifest.ttl
+++ b/lv2/lv2plug.in/ns/ext/atom/manifest.ttl
@@ -4,6 +4,5 @@
 <http://lv2plug.in/ns/ext/atom>
 	a lv2:Specification ;
 	lv2:minorVersion 0 ;
-	lv2:microVersion 4 ;
+	lv2:microVersion 5 ;
 	rdfs:seeAlso <atom.ttl> .
-
diff --git a/lv2/lv2plug.in/ns/ext/atom/util.h b/lv2/lv2plug.in/ns/ext/atom/util.h
index 6ba792c..9015a01 100644
--- a/lv2/lv2plug.in/ns/ext/atom/util.h
+++ b/lv2/lv2plug.in/ns/ext/atom/util.h
@@ -22,12 +22,11 @@
    This header is non-normative, it is provided for convenience.
 */
 
-#ifndef LV2_ATOM_HELPERS_H
-#define LV2_ATOM_HELPERS_H
+#ifndef LV2_ATOM_UTIL_H
+#define LV2_ATOM_UTIL_H
 
 #include <stdarg.h>
 #include <stdint.h>
-#include <stdio.h>
 #include <string.h>
 
 #include "lv2/lv2plug.in/ns/ext/atom/atom.h"
@@ -272,6 +271,9 @@ static const LV2_Atom_Object_Query LV2_OBJECT_QUERY_END = { 0, NULL };
    sweep.  By allocating @p query on the stack, objects can be "queried"
    quickly without allocating any memory.  This function is realtime safe.
 
+   This function can only do "flat" queries, it is not smart enough to match
+   variables in nested objects.
+
    For example:
    @code
    const LV2_Atom* name = NULL;
@@ -281,12 +283,12 @@ static const LV2_Atom_Object_Query LV2_OBJECT_QUERY_END = { 0, NULL };
        { urids.eg_age,  &age },
        LV2_OBJECT_QUERY_END
    };
-   lv2_object_get(obj, q);
+   lv2_object_query(obj, q);
    // name and age are now set to the appropriate values in obj, or NULL.
    @endcode
 */
 static inline int
-lv2_object_get(const LV2_Atom_Object* object, LV2_Atom_Object_Query* query)
+lv2_object_query(const LV2_Atom_Object* object, LV2_Atom_Object_Query* query)
 {
 	int matches   = 0;
 	int n_queries = 0;
@@ -324,19 +326,19 @@ lv2_object_get(const LV2_Atom_Object* object, LV2_Atom_Object_Query* query)
    @code
    const LV2_Atom* name = NULL;
    const LV2_Atom* age  = NULL;
-   lv2_object_getv(obj,
-                   uris.name_key, &name,
-                   uris.age_key,  &age,
-                   0);
+   lv2_object_get(obj,
+                  uris.name_key, &name,
+                  uris.age_key,  &age,
+                  0);
    @endcode
 */
 static inline int
-lv2_object_getv(const LV2_Atom_Object* object, ...)
+lv2_object_get(const LV2_Atom_Object* object, ...)
 {
 	int matches   = 0;
 	int n_queries = 0;
 
-	/* Count number of query keys so we can short-circuit when done */
+	/* Count number of keys so we can short-circuit when done */
 	va_list args;
 	va_start(args, object);
 	for (n_queries = 0; va_arg(args, uint32_t); ++n_queries) {
@@ -369,4 +371,4 @@ lv2_object_getv(const LV2_Atom_Object* object, ...)
    @}
 */
 
-#endif /* LV2_ATOM_HELPERS_H */
+#endif /* LV2_ATOM_UTIL_H */