Clean up slv2.h.

git-svn-id: http://svn.drobilla.net/lad/trunk/slv2@3034 a436a847-0d15-0410-975c-d299462d15a1

1 files changed, 755 insertions, 629 deletions

diff --git a/slv2/slv2.h b/slv2/slv2.h
index 4855202..b6aae6f 100644
--- a/slv2/slv2.h
+++ b/slv2/slv2.h
@@ -16,8 +16,12 @@
  * 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
  */
 
-#ifndef SLV2_SLV2_H__
-#define SLV2_SLV2_H__
+/**
+   @file slv2.h API for SLV2, a lightweight LV2 host library.
+*/
+
+#ifndef SLV2_SLV2_H
+#define SLV2_SLV2_H
 
 #include <stdint.h>
 #include <stdbool.h>
@@ -25,30 +29,25 @@
 #include "lv2/lv2plug.in/ns/lv2core/lv2.h"
 #include "lv2/lv2plug.in/ns/extensions/ui/ui.h"
 
-#ifdef __cplusplus
-extern "C" {
-#endif
-
-#if defined _WIN32 || defined __CYGWIN__
-	#define SLV2_LIB_IMPORT __declspec(dllimport)
-	#define SLV2_LIB_EXPORT __declspec(dllexport)
-#else
-	#define SLV2_LIB_IMPORT __attribute__ ((visibility("default")))
-	#define SLV2_LIB_EXPORT __attribute__ ((visibility("default")))
-#endif
-
-#ifdef SLV2_SHARED  // Building a shared library
-	#ifdef SLV2_INTERNAL  // Building SLV2 (not using it)
+#ifdef SLV2_SHARED
+	#if defined _WIN32 || defined __CYGWIN__
+		#define SLV2_LIB_IMPORT __declspec(dllimport)
+		#define SLV2_LIB_EXPORT __declspec(dllexport)
+	#else
+		#define SLV2_LIB_IMPORT __attribute__ ((visibility("default")))
+		#define SLV2_LIB_EXPORT __attribute__ ((visibility("default")))
+	#endif
+	#ifdef SLV2_INTERNAL
 		#define SLV2_API SLV2_LIB_EXPORT
 	#else
 		#define SLV2_API SLV2_LIB_IMPORT
 	#endif
-#else  // Building a static library
+#else
 	#define SLV2_API
 #endif
 
 #if (__GNUC__ > 3 || (__GNUC__ == 3 && __GNUC_MINOR__ >= 1))
-	#ifdef SLV2_INTERNAL  // Building SLV2 (not using it)
+	#ifdef SLV2_INTERNAL
 		#define SLV2_DEPRECATED
 	#else
 		#define SLV2_DEPRECATED __attribute__((__deprecated__))
@@ -57,6 +56,10 @@ extern "C" {
 	#define SLV2_DEPRECATED
 #endif
 
+#ifdef __cplusplus
+extern "C" {
+#endif
+
 #define SLV2_NAMESPACE_LV2      "http://lv2plug.in/ns/lv2core#"
 #define SLV2_PORT_CLASS_PORT    "http://lv2plug.in/ns/lv2core#Port"
 #define SLV2_PORT_CLASS_INPUT   "http://lv2plug.in/ns/lv2core#InputPort"
@@ -80,225 +83,255 @@ typedef void* SLV2ScalePoints;    /**< array<ScalePoint>. */
 typedef void* SLV2UIs;            /**< set<UI>. */
 typedef void* SLV2Values;         /**< array<Value>. */
 
-/** @defgroup slv2 SLV2
- * SLV2 is a simple yet powerful C API for using LV2 plugins.
- *
- * For more information about LV2, see <http://lv2plug.in>.
- * For more information about SLV2, see <http://drobilla.net/software/slv2>.
- * @{
- */
-
-/** @name Value
- * @{
- */
-
-/** Convert a file URI string to a local path string.
- * For example, "file://foo/bar/baz.ttl" returns "/foo/bar/baz.ttl".
- * Return value is shared and must not be deleted by caller.
- * @return @a uri converted to a path, or NULL on failure (URI is not local).
- */
+/**
+   @defgroup slv2 SLV2
+   SLV2 is a simple yet powerful C API for using LV2 plugins.
+ 
+   For more information about LV2, see <http://lv2plug.in>.
+   For more information about SLV2, see <http://drobilla.net/software/slv2>.
+   @{
+*/
+
+/**
+   @name Value
+   @{
+*/
+
+/**
+   Convert a file URI string to a local path string.
+   For example, "file://foo/bar/baz.ttl" returns "/foo/bar/baz.ttl".
+   Return value is shared and must not be deleted by caller.
+   @return @a uri converted to a path, or NULL on failure (URI is not local).
+*/
 SLV2_API
-const char* slv2_uri_to_path(const char* uri);
+const char*
+slv2_uri_to_path(const char* uri);
 
-/** Create a new URI value.
- * Returned value must be freed by caller with slv2_value_free.
- */
+/**
+   Create a new URI value.
+   Returned value must be freed by caller with slv2_value_free.
+*/
 SLV2_API
 SLV2Value
 slv2_value_new_uri(SLV2World world, const char* uri);
 
-/** Create a new string value (with no language).
- * Returned value must be freed by caller with slv2_value_free.
- */
+/**
+   Create a new string value (with no language).
+   Returned value must be freed by caller with slv2_value_free.
+*/
 SLV2_API
 SLV2Value
 slv2_value_new_string(SLV2World world, const char* str);
 
-/** Create a new integer value.
- * Returned value must be freed by caller with slv2_value_free.
- */
+/**
+   Create a new integer value.
+   Returned value must be freed by caller with slv2_value_free.
+*/
 SLV2_API
 SLV2Value
 slv2_value_new_int(SLV2World world, int val);
 
-/** Create a new floating point value.
- * Returned value must be freed by caller with slv2_value_free.
- */
+/**
+   Create a new floating point value.
+   Returned value must be freed by caller with slv2_value_free.
+*/
 SLV2_API
 SLV2Value
 slv2_value_new_float(SLV2World world, float val);
 
-/** Create a new boolean value.
- * Returned value must be freed by caller with slv2_value_free.
- */
+/**
+   Create a new boolean value.
+   Returned value must be freed by caller with slv2_value_free.
+*/
 SLV2_API
 SLV2Value
 slv2_value_new_bool(SLV2World world, bool val);
 
-/** Free an SLV2Value.
- */
+/**
+   Free an SLV2Value.
+*/
 SLV2_API
 void
 slv2_value_free(SLV2Value val);
 
-/** Duplicate an SLV2Value.
- */
+/**
+   Duplicate an SLV2Value.
+*/
 SLV2_API
 SLV2Value
 slv2_value_duplicate(SLV2Value val);
 
-/** Return whether two values are equivalent.
- */
+/**
+   Return whether two values are equivalent.
+*/
 SLV2_API
 bool
 slv2_value_equals(SLV2Value value, SLV2Value other);
 
-/** Return this value as a Turtle/SPARQL token.
- * <table>
- * <caption>Example Turtle Tokens</caption>
- * <tr><th>URI</th><td>&lt;http://example.org/foo &gt;</td></tr>
- * <tr><th>QName</td><td>doap:name</td></tr>
- * <tr><th>String</td><td>"this is a string"</td></tr>
- * <tr><th>Float</td><td>1.0</td></tr>
- * <tr><th>Integer</td><td>1</td></tr>
- * <tr><th>Boolean</td><td>true</td></tr>
- * </table>
- */
+/**
+   Return this value as a Turtle/SPARQL token.
+   <table>
+   <caption>Example Turtle Tokens</caption>
+   <tr><th>URI</th><td>&lt;http://example.org/foo &gt;</td></tr>
+   <tr><th>QName</td><td>doap:name</td></tr>
+   <tr><th>String</td><td>"this is a string"</td></tr>
+   <tr><th>Float</td><td>1.0</td></tr>
+   <tr><th>Integer</td><td>1</td></tr>
+   <tr><th>Boolean</td><td>true</td></tr>
+   </table>
+*/
 SLV2_API
 char*
 slv2_value_get_turtle_token(SLV2Value value);
 
-/** Return whether the value is a URI (resource).
- */
+/**
+   Return whether the value is a URI (resource).
+*/
 SLV2_API
 bool
 slv2_value_is_uri(SLV2Value value);
 
-/** Return this value as a URI string, e.g. "http://example.org/foo".
- * Valid to call only if slv2_value_is_uri(@a value) returns true.
- * Returned value is owned by @a value and must not be freed by caller.
- */
+/**
+   Return this value as a URI string, e.g. "http://example.org/foo".
+   Valid to call only if slv2_value_is_uri(@a value) returns true.
+   Returned value is owned by @a value and must not be freed by caller.
+*/
 SLV2_API
 const char*
 slv2_value_as_uri(SLV2Value value);
 
-/** Return whether the value is a blank node (resource with no URI).
- */
+/**
+   Return whether the value is a blank node (resource with no URI).
+*/
 SLV2_API
 bool
 slv2_value_is_blank(SLV2Value value);
 
-/** Return this value as a blank node identifier, e.g. "genid03".
- * Valid to call only if slv2_value_is_blank(@a value) returns true.
- * Returned value is owned by @a value and must not be freed by caller.
- */
+/**
+   Return this value as a blank node identifier, e.g. "genid03".
+   Valid to call only if slv2_value_is_blank(@a value) returns true.
+   Returned value is owned by @a value and must not be freed by caller.
+*/
 SLV2_API
 const char*
 slv2_value_as_blank(SLV2Value value);
 
-/** Return whether this value is a literal (i.e. not a URI).
- * Returns true if @a value is a string or numeric value.
- */
+/**
+   Return whether this value is a literal (i.e. not a URI).
+   Returns true if @a value is a string or numeric value.
+*/
 SLV2_API
 bool
 slv2_value_is_literal(SLV2Value value);
 
-/** Return whether this value is a string literal.
- * Returns true if @a value is a string (but not  numeric) value.
- */
+/**
+   Return whether this value is a string literal.
+   Returns true if @a value is a string (but not  numeric) value.
+*/
 SLV2_API
 bool
 slv2_value_is_string(SLV2Value value);
 
-/** Return @a value as a string.
- */
+/**
+   Return @a value as a string.
+*/
 SLV2_API
 const char*
 slv2_value_as_string(SLV2Value value);
 
-/** Return whether this value is a decimal literal.
- */
+/**
+   Return whether this value is a decimal literal.
+*/
 SLV2_API
 bool
 slv2_value_is_float(SLV2Value value);
 
-/** Return @a value as a float.
- * Valid to call only if slv2_value_is_float(@a value) or
- * slv2_value_is_int(@a value) returns true.
- */
+/**
+   Return @a value as a float.
+   Valid to call only if slv2_value_is_float(@a value) or
+   slv2_value_is_int(@a value) returns true.
+*/
 SLV2_API
 float
 slv2_value_as_float(SLV2Value value);
 
-/** Return whether this value is an integer literal.
- */
+/**
+   Return whether this value is an integer literal.
+*/
 SLV2_API
 bool
 slv2_value_is_int(SLV2Value value);
 
-/** Return @a value as an integer.
- * Valid to call only if slv2_value_is_int(@a value) returns true.
- */
+/**
+   Return @a value as an integer.
+   Valid to call only if slv2_value_is_int(@a value) returns true.
+*/
 SLV2_API
 int
 slv2_value_as_int(SLV2Value value);
 
-/** Return whether this value is a boolean.
- */
+/**
+   Return whether this value is a boolean.
+*/
 SLV2_API
 bool
 slv2_value_is_bool(SLV2Value value);
 
-/** Return @a value as a bool.
- * Valid to call only if slv2_value_is_bool(@a value) returns true.
- */
+/**
+   Return @a value as a bool.
+   Valid to call only if slv2_value_is_bool(@a value) returns true.
+*/
 SLV2_API
 bool
 slv2_value_as_bool(SLV2Value value);
 
-/** @} */
-/** @name Collections
- * SLV2 has several collection types for holding various types of value:
- * <ul>
- * <li>SLV2Plugins (function prefix "slv2_plugins_")</li>
- * <li>SLV2PluginClasses (function prefix "slv2_plugin_classes_")</li>
- * <li>SLV2ScalePoints (function prefix "slv2_scale_points_")</li>
- * <li>SLV2Values (function prefix "slv2_values_")</li>
- * <li>SLV2UIs (function prefix "slv2_uis_")</li>
- * </ul>
- *
- * Each collection type supports the following functions:
- * <ul>
- * <li>PREFIX_free (coll)</li>
- * <li>PREFIX_size (coll)</li>
- * <li>PREFIX_get_at (coll, index)</li>
- * </ul>
- * @{
- */
+/**
+   @}
+   @name Collections
+   SLV2 has several collection types for holding various types of value:
+   <ul>
+   <li>SLV2Plugins (function prefix "slv2_plugins_")</li>
+   <li>SLV2PluginClasses (function prefix "slv2_plugin_classes_")</li>
+   <li>SLV2ScalePoints (function prefix "slv2_scale_points_")</li>
+   <li>SLV2Values (function prefix "slv2_values_")</li>
+   <li>SLV2UIs (function prefix "slv2_uis_")</li>
+   </ul>
+
+   Each collection type supports the following functions:
+   <ul>
+   <li>PREFIX_free (coll)</li>
+   <li>PREFIX_size (coll)</li>
+   <li>PREFIX_get_at (coll, index)</li>
+   </ul>
+   @{
+*/
 
 #define SLV2_COLLECTION(CollType, ElemType, prefix) \
 \
-/** Free @a collection.
- */ \
+/**
+   Free @a collection.
+*/ \
 SLV2_API \
 void \
 prefix ## _free(CollType collection); \
 \
 \
-/** Get the number of elements in @a collection.
- */ \
+/**
+   Get the number of elements in @a collection.
+*/ \
 SLV2_API \
 unsigned \
 prefix ## _size(CollType collection); \
 \
 \
-/** Get an element from @a collection by index.
- * @a index has no significance other than as an index into this collection.
- * Any @a index not less than the size of the collection will return NULL,
- * so all elements in a collection can be enumerated by repeated calls
- * to this function starting with @a index = 0.
- * @return NULL if @a index is out of range.
- */ \
+/**
+   Get an element from @a collection by index.
+   @a index has no significance other than as an index into this collection.
+   Any @a index not less than the size of the collection will return NULL,
+   so all elements in a collection can be enumerated by repeated calls
+   to this function starting with @a index = 0.
+   @return NULL if @a index is out of range.
+*/ \
 SLV2_API \
 ElemType \
 prefix ## _get_at(CollType collection, \
@@ -309,386 +342,423 @@ SLV2_COLLECTION(SLV2ScalePoints, SLV2ScalePoint, slv2_scale_points)
 SLV2_COLLECTION(SLV2UIs, SLV2UI, slv2_uis)
 SLV2_COLLECTION(SLV2Values, SLV2Value, slv2_values)
 
-/** Free a plugin collection.
- * Freeing a plugin collection does not destroy the plugins it contains
- * (plugins are owned by the world). @a plugins is invalid after this call.
- */
+/**
+   Free a plugin collection.
+   Freeing a plugin collection does not destroy the plugins it contains
+   (plugins are owned by the world). @a plugins is invalid after this call.
+*/
 SLV2_API
 void
 slv2_plugins_free(SLV2World   world,
                   SLV2Plugins plugins);
 
-/** Get the number of plugins in the collection.
- */
+/**
+   Get the number of plugins in the collection.
+*/
 SLV2_API
 unsigned
 slv2_plugins_size(SLV2Plugins plugins);
 
-/** Get a plugin from @a plugins by URI.
- * Return value is shared (stored in @a plugins) and must not be freed or
- * modified by the caller in any way.
- * @return NULL if no plugin with @a uri is found in @a plugins.
- */
+/**
+   Get a plugin from @a plugins by URI.
+   Return value is shared (stored in @a plugins) and must not be freed or
+   modified by the caller in any way.
+   @return NULL if no plugin with @a uri is found in @a plugins.
+*/
 SLV2_API
 SLV2Plugin
 slv2_plugins_get_by_uri(SLV2Plugins plugins,
                         SLV2Value   uri);
 
-/** Get a plugin from @a plugins by index.
- * @a index has no significance other than as an index into this plugins.
- * Any @a index not less than slv2_plugins_get_length(plugins) will return NULL,
- * so all plugins in a plugins can be enumerated by repeated calls
- * to this function starting with @a index = 0.
- * @return NULL if @a index out of range.
- */
+/**
+   Get a plugin from @a plugins by index.
+   @a index has no significance other than as an index into this plugins.
+   Any @a index not less than slv2_plugins_get_length(plugins) will return NULL,
+   so all plugins in a plugins can be enumerated by repeated calls
+   to this function starting with @a index = 0.
+   @return NULL if @a index out of range.
+*/
 SLV2_API
 SLV2Plugin
 slv2_plugins_get_at(SLV2Plugins plugins,
                     unsigned    index);
 
-/** Get a plugin class from @a classes by URI.
- * Return value is shared (stored in @a classes) and must not be freed or
- * modified by the caller in any way.
- * @return NULL if no plugin class with @a uri is found in @a classes.
- */
+/**
+   Get a plugin class from @a classes by URI.
+   Return value is shared (stored in @a classes) and must not be freed or
+   modified by the caller in any way.
+   @return NULL if no plugin class with @a uri is found in @a classes.
+*/
 SLV2_API
 SLV2PluginClass
 slv2_plugin_classes_get_by_uri(SLV2PluginClasses classes,
                                SLV2Value         uri);
 
-/** Allocate a new, empty SLV2ScalePoints.
- */
+/**
+   Allocate a new, empty SLV2ScalePoints.
+*/
 SLV2_API
 SLV2ScalePoints
 slv2_scale_points_new(void);
 
-/** Allocate a new, empty SLV2Values.
- */
+/**
+   Allocate a new, empty SLV2Values.
+*/
 SLV2_API
 SLV2Values
 slv2_values_new(void);
 
-/** Return whether @a values contains @a value.
- */
+/**
+   Return whether @a values contains @a value.
+*/
 SLV2_API
 bool
 slv2_values_contains(SLV2Values values, SLV2Value value);
 
-/** @} */
-/** @name World
- * The "world" represents all SLV2 state, and is used to discover/load/cache
- * LV2 data (plugins, UIs, and extensions).
- * Normal hosts which just need to load plugins by URI should simply use
- * @ref slv2_world_load_all to discover/load the system's LV2 resources.
- * @{
- */
-
-/** Initialize a new, empty world.
- * If initialization fails, NULL is returned.
- */
+/**
+   @}
+   @name World
+   The "world" represents all SLV2 state, and is used to discover/load/cache
+   LV2 data (plugins, UIs, and extensions).
+   Normal hosts which just need to load plugins by URI should simply use
+   @ref slv2_world_load_all to discover/load the system's LV2 resources.
+   @{
+*/
+
+/**
+   Initialize a new, empty world.
+   If initialization fails, NULL is returned.
+*/
 SLV2_API
 SLV2World
 slv2_world_new(void);
 
-/** Enable/disable language filtering.
- * Language filtering applies to any functions that return (a) value(s).
- * With filtering enabled, SLV2 will automatically return the best value(s)
- * for the current LANG.  With filtering disabled, all matching values will
- * be returned regardless of language tag.  Filtering is enabled by default.
- */
+/**
+   Enable/disable language filtering.
+   Language filtering applies to any functions that return (a) value(s).
+   With filtering enabled, SLV2 will automatically return the best value(s)
+   for the current LANG.  With filtering disabled, all matching values will
+   be returned regardless of language tag.  Filtering is enabled by default.
+*/
 #define SLV2_OPTION_FILTER_LANG "http://drobilla.net/ns/slv2#filter-lang"
 
-/** Set an SLV2 option for @a world.
- */
+/**
+   Set an SLV2 option for @a world.
+*/
 SLV2_API
 void
 slv2_world_set_option(SLV2World       world,
                       const char*     uri,
                       const SLV2Value value);
 
-/** Destroy the world, mwahaha.
- * Note that destroying @a world will destroy all the objects it contains
- * (e.g. instances of SLV2Plugin).  Do not destroy the world until you are
- * finished with all objects that came from it.
- */
+/**
+   Destroy the world, mwahaha.
+   Note that destroying @a world will destroy all the objects it contains
+   (e.g. instances of SLV2Plugin).  Do not destroy the world until you are
+   finished with all objects that came from it.
+*/
 SLV2_API
 void
 slv2_world_free(SLV2World world);
 
-/** Load all installed LV2 bundles on the system.
- * This is the recommended way for hosts to load LV2 data.  It implements the
- * established/standard best practice for discovering all LV2 data on the
- * system.  The environment variable LV2_PATH may be used to control where
- * this function will look for bundles.
- *
- * Hosts should use this function rather than explicitly load bundles, except
- * in special circumstances (e.g. development utilities, or hosts that ship
- * with special plugin bundles which are installed to a known location).
- */
+/**
+   Load all installed LV2 bundles on the system.
+   This is the recommended way for hosts to load LV2 data.  It implements the
+   established/standard best practice for discovering all LV2 data on the
+   system.  The environment variable LV2_PATH may be used to control where
+   this function will look for bundles.
+ 
+   Hosts should use this function rather than explicitly load bundles, except
+   in special circumstances (e.g. development utilities, or hosts that ship
+   with special plugin bundles which are installed to a known location).
+*/
 SLV2_API
 void
 slv2_world_load_all(SLV2World world);
 
-/** Load a specific bundle.
- * @a bundle_uri must be a fully qualified URI to the bundle directory,
- * with the trailing slash, eg. file:///usr/lib/lv2/foo.lv2/
- *
- * Normal hosts should not need this function (use slv2_world_load_all).
- *
- * Hosts MUST NOT attach any long-term significance to bundle paths
- * (e.g. in save files), since there are no guarantees they will remain
- * unchanged between (or even during) program invocations. Plugins (among
- * other things) MUST be identified by URIs (not paths) in save files.
- */
+/**
+   Load a specific bundle.
+   @a bundle_uri must be a fully qualified URI to the bundle directory,
+   with the trailing slash, eg. file:///usr/lib/lv2/foo.lv2/
+ 
+   Normal hosts should not need this function (use slv2_world_load_all).
+ 
+   Hosts MUST NOT attach any long-term significance to bundle paths
+   (e.g. in save files), since there are no guarantees they will remain
+   unchanged between (or even during) program invocations. Plugins (among
+   other things) MUST be identified by URIs (not paths) in save files.
+*/
 SLV2_API
 void
 slv2_world_load_bundle(SLV2World world,
                        SLV2Value bundle_uri);
 
-/** Get the parent of all other plugin classes, lv2:Plugin.
- */
+/**
+   Get the parent of all other plugin classes, lv2:Plugin.
+*/
 SLV2_API
 SLV2PluginClass
 slv2_world_get_plugin_class(SLV2World world);
 
-/** Return a list of all found plugin classes.
- * Returned list is owned by world and must not be freed by the caller.
- */
+/**
+   Return a list of all found plugin classes.
+   Returned list is owned by world and must not be freed by the caller.
+*/
 SLV2_API
 SLV2PluginClasses
 slv2_world_get_plugin_classes(SLV2World world);
 
-/** Return a list of all found plugins.
- * The returned list contains just enough references to query
- * or instantiate plugins.  The data for a particular plugin will not be
- * loaded into memory until a call to an slv2_plugin_* function results in
- * a query (at which time the data is cached with the SLV2Plugin so future
- * queries are very fast).
- *
- * Returned list must be freed by user with slv2_plugins_free.  The contained
- * plugins are owned by @a world and must not be freed by caller.
- */
+/**
+   Return a list of all found plugins.
+   The returned list contains just enough references to query
+   or instantiate plugins.  The data for a particular plugin will not be
+   loaded into memory until a call to an slv2_plugin_* function results in
+   a query (at which time the data is cached with the SLV2Plugin so future
+   queries are very fast).
+ 
+   Returned list must be freed by user with slv2_plugins_free.  The contained
+   plugins are owned by @a world and must not be freed by caller.
+*/
 SLV2_API
 SLV2Plugins
 slv2_world_get_all_plugins(SLV2World world);
 
-/** Return a list of found plugins filtered by a user-defined filter function.
- * All plugins currently found in @a world that return true when passed to
- * @a include (a pointer to a function which takes an SLV2Plugin and returns
- * a bool) will be in the returned list.
- *
- * Returned list must be freed by user with slv2_plugins_free.  The contained
- * plugins are owned by @a world and must not be freed by caller.
- */
+/**
+   Return a list of found plugins filtered by a user-defined filter function.
+   All plugins currently found in @a world that return true when passed to
+   @a include (a pointer to a function which takes an SLV2Plugin and returns
+   a bool) will be in the returned list.
+ 
+   Returned list must be freed by user with slv2_plugins_free.  The contained
+   plugins are owned by @a world and must not be freed by caller.
+*/
 SLV2_API
 SLV2Plugins
 slv2_world_get_plugins_by_filter(SLV2World world,
                                  bool (*include)(SLV2Plugin));
 
-/** Return the plugin with the given @a uri, or NULL if not found.
- */
+/**
+   Return the plugin with the given @a uri, or NULL if not found.
+*/
 SLV2_API
 SLV2Plugin
 slv2_world_get_plugin_by_uri_string(SLV2World   world,
                                     const char* uri);
 
-/** @} */
-/** @name Plugin
- * @{
- */
-
-/** Check if @a plugin is valid.
- * This is not a rigorous validator, but can be used to reject some malformed
- * plugins that could cause bugs (e.g. plugins with missing required fields).
- *
- * Note that normal hosts do NOT need to use this - slv2 does not
- * load invalid plugins into plugin lists.  This is included for plugin
- * testing utilities, etc.
- * @return true iff @a plugin is valid.
- */
+/**
+   @}
+   @name Plugin
+   @{
+*/
+
+/**
+   Check if @a plugin is valid.
+   This is not a rigorous validator, but can be used to reject some malformed
+   plugins that could cause bugs (e.g. plugins with missing required fields).
+ 
+   Note that normal hosts do NOT need to use this - slv2 does not
+   load invalid plugins into plugin lists.  This is included for plugin
+   testing utilities, etc.
+   @return true iff @a plugin is valid.
+*/
 SLV2_API
 bool
 slv2_plugin_verify(SLV2Plugin plugin);
 
-/** Get the URI of @a plugin.
- * Any serialization that refers to plugins should refer to them by this.
- * Hosts SHOULD NOT save any filesystem paths, plugin indexes, etc. in saved
- * files; save only the URI.
- *
- * The URI is a globally unique identifier for one specific plugin.  Two
- * plugins with the same URI are compatible in port signature, and should
- * be guaranteed to work in a compatible and consistent way.  If a plugin
- * is upgraded in an incompatible way (eg if it has different ports), it
- * MUST have a different URI than it's predecessor.
- *
- * @return A shared URI value which must not be modified or freed.
- */
+/**
+   Get the URI of @a plugin.
+   Any serialization that refers to plugins should refer to them by this.
+   Hosts SHOULD NOT save any filesystem paths, plugin indexes, etc. in saved
+   files; save only the URI.
+ 
+   The URI is a globally unique identifier for one specific plugin.  Two
+   plugins with the same URI are compatible in port signature, and should
+   be guaranteed to work in a compatible and consistent way.  If a plugin
+   is upgraded in an incompatible way (eg if it has different ports), it
+   MUST have a different URI than it's predecessor.
+ 
+   @return A shared URI value which must not be modified or freed.
+*/
 SLV2_API
 SLV2Value
 slv2_plugin_get_uri(SLV2Plugin plugin);
 
-/** Get the (resolvable) URI of the plugin's "main" bundle.
- * This returns the URI of the bundle where the plugin itself was found.
- * Note that the data for a plugin may be spread over many bundles, that is,
- * slv2_plugin_get_data_uris may return URIs which are not within this bundle.
- *
- * Typical hosts should not need to use this function.
- * Note this always returns a fully qualified URI.  If you want a local
- * filesystem path, use slv2_uri_to_path.
- * @return a shared string which must not be modified or freed.
- */
+/**
+   Get the (resolvable) URI of the plugin's "main" bundle.
+   This returns the URI of the bundle where the plugin itself was found.
+   Note that the data for a plugin may be spread over many bundles, that is,
+   slv2_plugin_get_data_uris may return URIs which are not within this bundle.
+ 
+   Typical hosts should not need to use this function.
+   Note this always returns a fully qualified URI.  If you want a local
+   filesystem path, use slv2_uri_to_path.
+   @return a shared string which must not be modified or freed.
+*/
 SLV2_API
 SLV2Value
 slv2_plugin_get_bundle_uri(SLV2Plugin plugin);
 
-/** Get the (resolvable) URIs of the RDF data files that define a plugin.
- * Typical hosts should not need to use this function.
- * Note this always returns fully qualified URIs.  If you want local
- * filesystem paths, use slv2_uri_to_path.
- * @return a list of complete URLs eg. "file:///foo/ABundle.lv2/aplug.ttl",
- * which is shared and must not be modified or freed.
- */
+/**
+   Get the (resolvable) URIs of the RDF data files that define a plugin.
+   Typical hosts should not need to use this function.
+   Note this always returns fully qualified URIs.  If you want local
+   filesystem paths, use slv2_uri_to_path.
+   @return a list of complete URLs eg. "file:///foo/ABundle.lv2/aplug.ttl",
+   which is shared and must not be modified or freed.
+*/
 SLV2_API
 SLV2Values
 slv2_plugin_get_data_uris(SLV2Plugin plugin);
 
-/** Get the (resolvable) URI of the shared library for @a plugin.
- * Note this always returns a fully qualified URI.  If you want a local
- * filesystem path, use slv2_uri_to_path.
- * @return a shared string which must not be modified or freed.
- */
+/**
+   Get the (resolvable) URI of the shared library for @a plugin.
+   Note this always returns a fully qualified URI.  If you want a local
+   filesystem path, use slv2_uri_to_path.
+   @return a shared string which must not be modified or freed.
+*/
 SLV2_API
 SLV2Value
 slv2_plugin_get_library_uri(SLV2Plugin plugin);
 
-/** Get the name of @a plugin.
- * This returns the name (doap:name) of the plugin.  The name may be
- * translated according to the current locale, this value MUST NOT be used
- * as a plugin identifier (use the URI for that).
- * Returned value must be freed by the caller.
- */
+/**
+   Get the name of @a plugin.
+   This returns the name (doap:name) of the plugin.  The name may be
+   translated according to the current locale, this value MUST NOT be used
+   as a plugin identifier (use the URI for that).
+   Returned value must be freed by the caller.
+*/
 SLV2_API
 SLV2Value
 slv2_plugin_get_name(SLV2Plugin plugin);
 
-/** Get the class this plugin belongs to (ie Filters).
- */
+/**
+   Get the class this plugin belongs to (ie Filters).
+*/
 SLV2_API
 SLV2PluginClass
 slv2_plugin_get_class(SLV2Plugin plugin);
 
-/** Get a value associated with the plugin in a plugin's data files.
- * @a predicate must be either a URI or a QName.
- *
- * Returns the ?object of all triples found of the form:
- *
- * <code>&lt;plugin-uri&gt; predicate ?object</code>
- *
- * May return NULL if the property was not found, or if object(s) is not
- * sensibly represented as an SLV2Values (e.g. blank nodes).
- * Return value must be freed by caller with slv2_values_free.
- */
+/**
+   Get a value associated with the plugin in a plugin's data files.
+   @a predicate must be either a URI or a QName.
+ 
+   Returns the ?object of all triples found of the form:
+ 
+   <code>&lt;plugin-uri&gt; predicate ?object</code>
+ 
+   May return NULL if the property was not found, or if object(s) is not
+   sensibly represented as an SLV2Values (e.g. blank nodes).
+   Return value must be freed by caller with slv2_values_free.
+*/
 SLV2_API
 SLV2Values
 slv2_plugin_get_value(SLV2Plugin p,
                       SLV2Value  predicate);
 
-/** Get a value associated with the plugin in a plugin's data files.
- * This function is identical to slv2_plugin_get_value, but takes a QName
- * string parameter for a predicate instead of an SLV2Value, which may be
- * more convenient.
- */
+/**
+   Get a value associated with the plugin in a plugin's data files.
+   This function is identical to slv2_plugin_get_value, but takes a QName
+   string parameter for a predicate instead of an SLV2Value, which may be
+   more convenient.
+*/
 SLV2_API
 SLV2Values
 slv2_plugin_get_value_by_qname(SLV2Plugin  p,
                                const char* predicate);
 
-/** Get a value associated with some subject in a plugin's data files.
- * @a predicate must be either a URI or a QName.
- *
- * Returns the ?object of all triples found of the form:
- *
- * <code>subject predicate ?object</code>
- *
- * This can be used to investigate URIs returned by slv2_plugin_get_value
- * (if information about it is contained in the plugin's data files).
- *
- * May return NULL if the property was not found, or if object is not
- * sensibly represented as an SLV2Values (e.g. blank nodes).
- * Return value must be freed by caller with slv2_values_free.
- */
+/**
+   Get a value associated with some subject in a plugin's data files.
+   @a predicate must be either a URI or a QName.
+ 
+   Returns the ?object of all triples found of the form:
+ 
+   <code>subject predicate ?object</code>
+ 
+   This can be used to investigate URIs returned by slv2_plugin_get_value
+   (if information about it is contained in the plugin's data files).
+ 
+   May return NULL if the property was not found, or if object is not
+   sensibly represented as an SLV2Values (e.g. blank nodes).
+   Return value must be freed by caller with slv2_values_free.
+*/
 SLV2_API
 SLV2Values
 slv2_plugin_get_value_for_subject(SLV2Plugin p,
                                   SLV2Value  subject_uri,
                                   SLV2Value  predicate_uri);
 
-/** Return whether a feature is supported by a plugin.
- * This will return true if the feature is an optional or required feature
- * of the plugin.
- */
+/**
+   Return whether a feature is supported by a plugin.
+   This will return true if the feature is an optional or required feature
+   of the plugin.
+*/
 SLV2_API
 bool
 slv2_plugin_has_feature(SLV2Plugin p,
                         SLV2Value  feature_uri);
 
-/** Get the LV2 Features supported (required or optionally) by a plugin.
- * A feature is "supported" by a plugin if it is required OR optional.
- *
- * Since required features have special rules the host must obey, this function
- * probably shouldn't be used by normal hosts.  Using slv2_plugin_get_optional_features
- * and slv2_plugin_get_required_features separately is best in most cases.
- *
- * Returned value must be freed by caller with slv2_values_free.
- */
+/**
+   Get the LV2 Features supported (required or optionally) by a plugin.
+   A feature is "supported" by a plugin if it is required OR optional.
+   *
+   Since required features have special rules the host must obey, this function
+   probably shouldn't be used by normal hosts.  Using slv2_plugin_get_optional_features
+   and slv2_plugin_get_required_features separately is best in most cases.
+   *
+   Returned value must be freed by caller with slv2_values_free.
+*/
 SLV2_API
 SLV2Values
 slv2_plugin_get_supported_features(SLV2Plugin p);
 
-/** Get the LV2 Features required by a plugin.
- * If a feature is required by a plugin, hosts MUST NOT use the plugin if they do not
- * understand (or are unable to support) that feature.
- *
- * All values returned here MUST be passed to the plugin's instantiate method
- * (along with data, if necessary, as defined by the feature specification)
- * or plugin instantiation will fail.
- *
- * Return value must be freed by caller with slv2_values_free.
- */
+/**
+   Get the LV2 Features required by a plugin.
+   If a feature is required by a plugin, hosts MUST NOT use the plugin if they do not
+   understand (or are unable to support) that feature.
+ 
+   All values returned here MUST be passed to the plugin's instantiate method
+   (along with data, if necessary, as defined by the feature specification)
+   or plugin instantiation will fail.
+ 
+   Return value must be freed by caller with slv2_values_free.
+*/
 SLV2_API
 SLV2Values
 slv2_plugin_get_required_features(SLV2Plugin p);
 
-/** Get the LV2 Features optionally supported by a plugin.
- * Hosts MAY ignore optional plugin features for whatever reasons.  Plugins
- * MUST operate (at least somewhat) if they are instantiated without being
- * passed optional features.
- *
- * Return value must be freed by caller with slv2_values_free.
- */
+/**
+   Get the LV2 Features optionally supported by a plugin.
+   Hosts MAY ignore optional plugin features for whatever reasons.  Plugins
+   MUST operate (at least somewhat) if they are instantiated without being
+   passed optional features.
+ 
+   Return value must be freed by caller with slv2_values_free.
+*/
 SLV2_API
 SLV2Values
 slv2_plugin_get_optional_features(SLV2Plugin p);
 
-/** Get the number of ports on this plugin.
- */
+/**
+   Get the number of ports on this plugin.
+*/
 SLV2_API
 uint32_t
 slv2_plugin_get_num_ports(SLV2Plugin p);
 
-/** Get the port ranges (minimum, maximum and default values) for all ports.
- * @a min_values, @a max_values and @a def_values must either point to an array
- * of N floats, where N is the value returned by slv2_plugin_get_num_ports()
- * for this plugin, or NULL.  The elements of the array will be set to the
- * the minimum, maximum and default values of the ports on this plugin,
- * with array index corresponding to port index.  If a port doesn't have a
- * minimum, maximum or default value, or the port's type is not float, the
- * corresponding array element will be set to NAN.
- *
- * This is a convenience method for the common case of getting the range of
- * all float ports on a plugin, and may be significantly faster than
- * repeated calls to slv2_port_get_range.
- */
+/**
+   Get the port ranges (minimum, maximum and default values) for all ports.
+   @a min_values, @a max_values and @a def_values must either point to an array
+   of N floats, where N is the value returned by slv2_plugin_get_num_ports()
+   for this plugin, or NULL.  The elements of the array will be set to the
+   the minimum, maximum and default values of the ports on this plugin,
+   with array index corresponding to port index.  If a port doesn't have a
+   minimum, maximum or default value, or the port's type is not float, the
+   corresponding array element will be set to NAN.
+ 
+   This is a convenience method for the common case of getting the range of
+   all float ports on a plugin, and may be significantly faster than
+   repeated calls to slv2_port_get_range.
+*/
 SLV2_API
 void
 slv2_plugin_get_port_ranges_float(SLV2Plugin p,
@@ -696,169 +766,188 @@ slv2_plugin_get_port_ranges_float(SLV2Plugin p,
                                   float*     max_values,
                                   float*     def_values);
 
-/** Get the number of ports on this plugin that are members of some class(es).
- * Note that this is a varargs function so ports fitting any type 'profile'
- * desired can be found quickly.  REMEMBER TO TERMINATE THE PARAMETER LIST
- * OF THIS FUNCTION WITH NULL OR VERY NASTY THINGS WILL HAPPEN.
- */
+/**
+   Get the number of ports on this plugin that are members of some class(es).
+   Note that this is a varargs function so ports fitting any type 'profile'
+   desired can be found quickly.  REMEMBER TO TERMINATE THE PARAMETER LIST
+   OF THIS FUNCTION WITH NULL OR VERY NASTY THINGS WILL HAPPEN.
+*/
 SLV2_API
 uint32_t
 slv2_plugin_get_num_ports_of_class(SLV2Plugin p,
                                    SLV2Value  class_1, ...);
 
-/** Return whether or not the plugin introduces (and reports) latency.
- * The index of the latency port can be found with slv2_plugin_get_latency_port
- * ONLY if this function returns true.
- */
+/**
+   Return whether or not the plugin introduces (and reports) latency.
+   The index of the latency port can be found with slv2_plugin_get_latency_port
+   ONLY if this function returns true.
+*/
 SLV2_API
 bool
 slv2_plugin_has_latency(SLV2Plugin p);
 
-/** Return the index of the plugin's latency port.
- * It is a fatal error to call this on a plugin without checking if the port
- * exists by first calling slv2_plugin_has_latency.
- *
- * Any plugin that introduces unwanted latency that should be compensated for
- * (by hosts with the ability/need) MUST provide this port, which is a control
- * rate output port that reports the latency for each cycle in frames.
- */
+/**
+   Return the index of the plugin's latency port.
+   It is a fatal error to call this on a plugin without checking if the port
+   exists by first calling slv2_plugin_has_latency.
+ 
+   Any plugin that introduces unwanted latency that should be compensated for
+   (by hosts with the ability/need) MUST provide this port, which is a control
+   rate output port that reports the latency for each cycle in frames.
+*/
 SLV2_API
 uint32_t
 slv2_plugin_get_latency_port_index(SLV2Plugin p);
 
-/** Get a port on @a plugin by @a index.
- */
+/**
+   Get a port on @a plugin by @a index.
+*/
 SLV2_API
 SLV2Port
 slv2_plugin_get_port_by_index(SLV2Plugin plugin,
                               uint32_t   index);
 
-/** Get a port on @a plugin by @a symbol.
- * Note this function is slower than slv2_plugin_get_port_by_index,
- * especially on plugins with a very large number of ports.
- */
+/**
+   Get a port on @a plugin by @a symbol.
+   Note this function is slower than slv2_plugin_get_port_by_index,
+   especially on plugins with a very large number of ports.
+*/
 SLV2_API
 SLV2Port
 slv2_plugin_get_port_by_symbol(SLV2Plugin plugin,
                                SLV2Value  symbol);
 
-/** Get the full name of the plugin's author.
- * Returns NULL if author name is not present.
- * Returned value must be freed by caller.
- */
+/**
+   Get the full name of the plugin's author.
+   Returns NULL if author name is not present.
+   Returned value must be freed by caller.
+*/
 SLV2_API
 SLV2Value
 slv2_plugin_get_author_name(SLV2Plugin plugin);
 
-/** Get the email address of the plugin's author.
- * Returns NULL if author email address is not present.
- * Returned value must be freed by caller.
- */
+/**
+   Get the email address of the plugin's author.
+   Returns NULL if author email address is not present.
+   Returned value must be freed by caller.
+*/
 SLV2_API
 SLV2Value
 slv2_plugin_get_author_email(SLV2Plugin plugin);
 
-/** Get the email address of the plugin's author.
- * Returns NULL if author homepage is not present.
- * Returned value must be freed by caller.
- */
+/**
+   Get the email address of the plugin's author.
+   Returns NULL if author homepage is not present.
+   Returned value must be freed by caller.
+*/
 SLV2_API
 SLV2Value
 slv2_plugin_get_author_homepage(SLV2Plugin plugin);
 
-/** @} */
-/** @name Port
- * @{
- */
+/**
+   @}
+   @name Port
+   @{
+*/
 
-/** Port analog of slv2_plugin_get_value.
- */
+/**
+   Port analog of slv2_plugin_get_value.
+*/
 SLV2_API
 SLV2Values
 slv2_port_get_value(SLV2Plugin plugin,
                     SLV2Port   port,
                     SLV2Value  predicate);
 
-/** Port analog of slv2_plugin_get_value_by_qname.
- */
+/**
+   Port analog of slv2_plugin_get_value_by_qname.
+*/
 SLV2_API
 SLV2Values
 slv2_port_get_value_by_qname(SLV2Plugin  plugin,
                              SLV2Port    port,
                              const char* predicate);
 
-/** Return the LV2 port properties of a port.
- */
+/**
+   Return the LV2 port properties of a port.
+*/
 SLV2_API
 SLV2Values
 slv2_port_get_properties(SLV2Plugin plugin,
                          SLV2Port   port);
 
-/** Return whether a port has a certain property.
- */
+/**
+   Return whether a port has a certain property.
+*/
 SLV2_API
 bool
 slv2_port_has_property(SLV2Plugin p,
                        SLV2Port   port,
                        SLV2Value  property_uri);
 
-/** Return whether a port is an event port and supports a certain event type.
- */
+/**
+   Return whether a port is an event port and supports a certain event type.
+*/
 SLV2_API
 bool
 slv2_port_supports_event(SLV2Plugin p,
                          SLV2Port   port,
                          SLV2Value  event_uri);
 
-/** Get the symbol of a port.
- * The 'symbol' is a short string, a valid C identifier.
- * Returned value is owned by @a port and must not be freed.
- */
+/**
+   Get the symbol of a port.
+   The 'symbol' is a short string, a valid C identifier.
+   Returned value is owned by @a port and must not be freed.
+*/
 SLV2_API
 SLV2Value
 slv2_port_get_symbol(SLV2Plugin plugin,
                      SLV2Port   port);
 
-/** Get the name of a port.
- * This is guaranteed to return the untranslated name (the doap:name in the
- * data file without a language tag).  Returned value must be freed by
- * the caller.
- */
+/**
+   Get the name of a port.
+   This is guaranteed to return the untranslated name (the doap:name in the
+   data file without a language tag).  Returned value must be freed by
+   the caller.
+*/
 SLV2_API
 SLV2Value
 slv2_port_get_name(SLV2Plugin plugin,
                    SLV2Port   port);
 
-/** Get all the classes of a port.
- * This can be used to determine if a port is an input, output, audio,
- * control, midi, etc, etc, though it's simpler to use slv2_port_is_a.
- * The returned list does not include lv2:Port, which is implied.
- * Returned value is shared and must not be destroyed by caller.
- */
+/**
+   Get all the classes of a port.
+   This can be used to determine if a port is an input, output, audio,
+   control, midi, etc, etc, though it's simpler to use slv2_port_is_a.
+   The returned list does not include lv2:Port, which is implied.
+   Returned value is shared and must not be destroyed by caller.
+*/
 SLV2_API
 SLV2Values
 slv2_port_get_classes(SLV2Plugin plugin,
                       SLV2Port   port);
 
-/** Determine if a port is of a given class (input, output, audio, etc).
- * For convenience/performance/extensibility reasons, hosts are expected to
- * create an SLV2Value for each port class they "care about".  Well-known type
- * URI strings are defined (e.g. SLV2_PORT_CLASS_INPUT) for convenience, but
- * this function is designed so that SLV2 is usable with any port types
- * without requiring explicit support in SLV2.
- */
+/**
+   Determine if a port is of a given class (input, output, audio, etc).
+   For convenience/performance/extensibility reasons, hosts are expected to
+   create an SLV2Value for each port class they "care about".  Well-known type
+   URI strings are defined (e.g. SLV2_PORT_CLASS_INPUT) for convenience, but
+   this function is designed so that SLV2 is usable with any port types
+   without requiring explicit support in SLV2.
+*/
 SLV2_API
 bool
 slv2_port_is_a(SLV2Plugin plugin,
                SLV2Port   port,
                SLV2Value  port_class);
 
-/** Get the default, minimum, and maximum values of a port.
- * @a def, @a min, and @a max are outputs, pass pointers to uninitialized
- * (i.e. NOT created with slv2_value_new) SLV2Value variables.  These will
- * be set to point at new values (which must be freed by the caller using
- * slv2_value_free), or NULL if the value does not exist.
- */
+/**
+   Get the default, minimum, and maximum values of a port.
+   @a def, @a min, and @a max are outputs, pass pointers to uninitialized
+   (i.e. NOT created with slv2_value_new) SLV2Value variables.  These will
+   be set to point at new values (which must be freed by the caller using
+   slv2_value_free), or NULL if the value does not exist.
+*/
 SLV2_API
 void
 slv2_port_get_range(SLV2Plugin plugin,
@@ -867,126 +956,140 @@ slv2_port_get_range(SLV2Plugin plugin,
                     SLV2Value* min,
                     SLV2Value* max);
 
-/** Get the scale points (enumeration values) of a port.
- * This returns a collection of 'interesting' named values of a port
- * (e.g. appropriate entries for a UI selector associated with this port).
- * Returned value may be NULL if @a port has no scale points, otherwise it
- * must be freed by caller with slv2_scale_points_free.
- */
+/**
+   Get the scale points (enumeration values) of a port.
+   This returns a collection of 'interesting' named values of a port
+   (e.g. appropriate entries for a UI selector associated with this port).
+   Returned value may be NULL if @a port has no scale points, otherwise it
+   must be freed by caller with slv2_scale_points_free.
+*/
 SLV2_API
 SLV2ScalePoints
 slv2_port_get_scale_points(SLV2Plugin plugin,
                            SLV2Port   port);
 
 
-/** @} */
-/** @name Scale Point
- * @{
- */
+/**
+   @}
+   @name Scale Point
+   @{
+*/
 
-/** Get the label of this scale point (enumeration value)
- * Returned value is owned by @a point and must not be freed.
- */
+/**
+   Get the label of this scale point (enumeration value)
+   Returned value is owned by @a point and must not be freed.
+*/
 SLV2_API
 SLV2Value
 slv2_scale_point_get_label(SLV2ScalePoint point);
 
-/** Get the value of this scale point (enumeration value)
- * Returned value is owned by @a point and must not be freed.
- */
+/**
+   Get the value of this scale point (enumeration value)
+   Returned value is owned by @a point and must not be freed.
+*/
 SLV2_API
 SLV2Value
 slv2_scale_point_get_value(SLV2ScalePoint point);
 
-/** @} */
-/** @name Plugin Class
- * @{
- */
+/**
+   @}
+   @name Plugin Class
+   @{
+*/
 
-/** Get the URI of this class' superclass.
- * Returned value is owned by @a plugin_class and must not be freed by caller.
- * Returned value may be NULL, if class has no parent.
- */
+/**
+   Get the URI of this class' superclass.
+   Returned value is owned by @a plugin_class and must not be freed by caller.
+   Returned value may be NULL, if class has no parent.
+*/
 SLV2_API
 SLV2Value
 slv2_plugin_class_get_parent_uri(SLV2PluginClass plugin_class);
 
-/** Get the URI of this plugin class.
- * Returned value is owned by @a plugin_class and must not be freed by caller.
- */
+/**
+   Get the URI of this plugin class.
+   Returned value is owned by @a plugin_class and must not be freed by caller.
+*/
 SLV2_API
 SLV2Value
 slv2_plugin_class_get_uri(SLV2PluginClass plugin_class);
 
-/** Get the label of this plugin class, ie "Oscillators".
- * Returned value is owned by @a plugin_class and must not be freed by caller.
- */
+/**
+   Get the label of this plugin class, ie "Oscillators".
+   Returned value is owned by @a plugin_class and must not be freed by caller.
+*/
 SLV2_API
 SLV2Value slv2_plugin_class_get_label(SLV2PluginClass plugin_class);
 
-/** Get the subclasses of this plugin class.
- * Returned value must be freed by caller with slv2_plugin_classes_free.
- */
+/**
+   Get the subclasses of this plugin class.
+   Returned value must be freed by caller with slv2_plugin_classes_free.
+*/
 SLV2_API
 SLV2PluginClasses
 slv2_plugin_class_get_children(SLV2PluginClass plugin_class);
 
-/** @} */
-/** @name Plugin Instance
- * @{
- */
+/**
+   @}
+   @name Plugin Instance
+   @{
+*/
 
 typedef struct _SLV2InstanceImpl* SLV2InstanceImpl;
 
 /* Instance of a plugin.
- * This is exposed in the ABI to allow inlining of performance critical
- * functions like slv2_instance_run (simple wrappers of functions in lv2.h).
- * This is for performance reasons, user code should not use this definition
- * in any way (which is why it is not machine documented).
- * Truly private implementation details are hidden via @a ref pimpl.
- */
+   This is exposed in the ABI to allow inlining of performance critical
+   functions like slv2_instance_run (simple wrappers of functions in lv2.h).
+   This is for performance reasons, user code should not use this definition
+   in any way (which is why it is not machine documented).
+   Truly private implementation details are hidden via @a ref pimpl.
+*/
 typedef struct _Instance {
 	const LV2_Descriptor* lv2_descriptor;
 	LV2_Handle            lv2_handle;
 	SLV2InstanceImpl      pimpl; ///< Private implementation
 }* SLV2Instance;
 
-/** Instantiate a plugin.
- * The returned value is a lightweight handle for an LV2 plugin instance,
- * it does not refer to @a plugin, or any other SLV2 state.  The caller must
- * eventually free it with slv2_instance_free.
- * @a features is a NULL-terminated array of features the host supports.
- * NULL may be passed if the host supports no additional features.
- * @return NULL if instantiation failed.
- */
+/**
+   Instantiate a plugin.
+   The returned value is a lightweight handle for an LV2 plugin instance,
+   it does not refer to @a plugin, or any other SLV2 state.  The caller must
+   eventually free it with slv2_instance_free.
+   @a features is a NULL-terminated array of features the host supports.
+   NULL may be passed if the host supports no additional features.
+   @return NULL if instantiation failed.
+*/
 SLV2_API
 SLV2Instance
 slv2_plugin_instantiate(SLV2Plugin               plugin,
                         double                   sample_rate,
                         const LV2_Feature*const* features);
 
-/** Free a plugin instance.
- * @a instance is invalid after this call.
- */
+/**
+   Free a plugin instance.
+   @a instance is invalid after this call.
+*/
 SLV2_API
 void
 slv2_instance_free(SLV2Instance instance);
 
 #ifndef SLV2_INTERNAL
 
-/** Get the URI of the plugin which @a instance is an instance of.
- * Returned string is shared and must not be modified or deleted.
- */
+/**
+   Get the URI of the plugin which @a instance is an instance of.
+   Returned string is shared and must not be modified or deleted.
+*/
 static inline const char*
 slv2_instance_get_uri(SLV2Instance instance)
 {
 	return instance->lv2_descriptor->URI;
 }
 
-/** Connect a port to a data location.
- * This may be called regardless of whether the plugin is activated,
- * activation and deactivation does not destroy port connections.
- */
+/**
+   Connect a port to a data location.
+   This may be called regardless of whether the plugin is activated,
+   activation and deactivation does not destroy port connections.
+*/
 static inline void
 slv2_instance_connect_port(SLV2Instance instance,
                            uint32_t     port_index,
@@ -996,11 +1099,12 @@ slv2_instance_connect_port(SLV2Instance instance,
 		(instance->lv2_handle, port_index, data_location);
 }
 
-/** Activate a plugin instance.
- * This resets all state information in the plugin, except for port data
- * locations (as set by slv2_instance_connect_port).  This MUST be called
- * before calling slv2_instance_run.
- */
+/**
+   Activate a plugin instance.
+   This resets all state information in the plugin, except for port data
+   locations (as set by slv2_instance_connect_port).  This MUST be called
+   before calling slv2_instance_run.
+*/
 static inline void
 slv2_instance_activate(SLV2Instance instance)
 {
@@ -1008,10 +1112,11 @@ slv2_instance_activate(SLV2Instance instance)
 		instance->lv2_descriptor->activate(instance->lv2_handle);
 }
 
-/** Run @a instance for @a sample_count frames.
- * If the hint lv2:hardRTCapable is set for this plugin, this function is
- * guaranteed not to block.
- */
+/**
+   Run @a instance for @a sample_count frames.
+   If the hint lv2:hardRTCapable is set for this plugin, this function is
+   guaranteed not to block.
+*/
 static inline void
 slv2_instance_run(SLV2Instance instance,
                   uint32_t     sample_count)
@@ -1019,10 +1124,11 @@ slv2_instance_run(SLV2Instance instance,
 	instance->lv2_descriptor->run(instance->lv2_handle, sample_count);
 }
 
-/** Deactivate a plugin instance.
- * Note that to run the plugin after this you must activate it, which will
- * reset all state information (except port connections).
- */
+/**
+   Deactivate a plugin instance.
+   Note that to run the plugin after this you must activate it, which will
+   reset all state information (except port connections).
+*/
 static inline void
 slv2_instance_deactivate(SLV2Instance instance)
 {
@@ -1030,10 +1136,11 @@ slv2_instance_deactivate(SLV2Instance instance)
 		instance->lv2_descriptor->deactivate(instance->lv2_handle);
 }
 
-/** Get extension data from the plugin instance.
- * The type and semantics of the data returned is specific to the particular
- * extension, though in all cases it is shared and must not be deleted.
- */
+/**
+   Get extension data from the plugin instance.
+   The type and semantics of the data returned is specific to the particular
+   extension, though in all cases it is shared and must not be deleted.
+*/
 static inline const void*
 slv2_instance_get_extension_data(SLV2Instance instance,
                                  const char*  uri)
@@ -1044,24 +1151,26 @@ slv2_instance_get_extension_data(SLV2Instance instance,
 		return NULL;
 }
 
-/** Get the LV2_Descriptor of the plugin instance.
- * Normally hosts should not need to access the LV2_Descriptor directly,
- * use the slv2_instance_* functions.
- *
- * The returned descriptor is shared and must not be deleted.
- */
+/**
+   Get the LV2_Descriptor of the plugin instance.
+   Normally hosts should not need to access the LV2_Descriptor directly,
+   use the slv2_instance_* functions.
+ 
+   The returned descriptor is shared and must not be deleted.
+*/
 static inline const LV2_Descriptor*
 slv2_instance_get_descriptor(SLV2Instance instance)
 {
 	return instance->lv2_descriptor;
 }
 
-/** Get the LV2_Handle of the plugin instance.
- * Normally hosts should not need to access the LV2_Handle directly,
- * use the slv2_instance_* functions.
- *
- * The returned handle is shared and must not be deleted.
- */
+/**
+   Get the LV2_Handle of the plugin instance.
+   Normally hosts should not need to access the LV2_Handle directly,
+   use the slv2_instance_* functions.
+ 
+   The returned handle is shared and must not be deleted.
+*/
 static inline LV2_Handle
 slv2_instance_get_handle(SLV2Instance instance)
 {
@@ -1070,108 +1179,116 @@ slv2_instance_get_handle(SLV2Instance instance)
 
 #endif /* SLV2_INTERNAL */
 
-/** @} */
-/** @name Plugin UI
- * @{
- */
+/**
+   @}
+   @name Plugin UI
+   @{
+*/
 
-/** Get a UI from @a uis by URI.
- * Return value is shared (stored in @a uis) and must not be freed or
- * modified by the caller in any way.
- * @return NULL if no UI with @a uri is found in @a list.
- */
+/**
+   Get a UI from @a uis by URI.
+   Return value is shared (stored in @a uis) and must not be freed or
+   modified by the caller in any way.
+   @return NULL if no UI with @a uri is found in @a list.
+*/
 SLV2_API
 SLV2UI
 slv2_uis_get_by_uri(SLV2UIs   uis,
                     SLV2Value uri);
 
-/** Get all UIs for @a plugin.
- * Returned value must be freed by caller using slv2_uis_free.
- */
+/**
+   Get all UIs for @a plugin.
+   Returned value must be freed by caller using slv2_uis_free.
+*/
 SLV2_API
 SLV2UIs
 slv2_plugin_get_uis(SLV2Plugin plugin);
 
-/** Get the default UI for @a plugin.
- * This function makes a best effort at choosing a default UI for the given
- * widget type. A native UI for the given widget type will be returned if one
- * exists, otherwise a UI which can be wrapped by SLV2 will be returned.
- *
- * This function makes the common case (a plugin with a single UI, or a single
- * UI per toolkit) simple, but is not fully powerful since a plugin may have
- * several usable UIs. To support multiple UIs per plugin, use
- * @ref slv2_ui_supported to determine which UIs are usable and choose a UI
- * to instantiate from among them.
- * 
- * @return NULL if there is no suitable UI.
- */
+/**
+   Get the default UI for @a plugin.
+   This function makes a best effort at choosing a default UI for the given
+   widget type. A native UI for the given widget type will be returned if one
+   exists, otherwise a UI which can be wrapped by SLV2 will be returned.
+ 
+   This function makes the common case (a plugin with a single UI, or a single
+   UI per toolkit) simple, but is not fully powerful since a plugin may have
+   several usable UIs. To support multiple UIs per plugin, use
+   @ref slv2_ui_supported to determine which UIs are usable and choose a UI
+   to instantiate from among them.
+   
+   @return NULL if there is no suitable UI.
+*/
 SLV2_API
 SLV2UI
 slv2_plugin_get_default_ui(SLV2Plugin plugin,
                            SLV2Value  widget_type_uri);
 
-/** @name Plugin UI
- * @{
- */
-
-/** Get the URI of a Plugin UI.
- * @param ui The Plugin UI
- * @return a shared value which must not be modified or freed.
- */
+/**
+   Get the URI of a Plugin UI.
+   @param ui The Plugin UI
+   @return a shared value which must not be modified or freed.
+*/
 SLV2_API
 SLV2Value
 slv2_ui_get_uri(SLV2UI ui);
 
-/** Return true iff @a ui can be instantiated to a widget of the given type.
- */
+/**
+   Return true iff @a ui can be instantiated to a widget of the given type.
+*/
 SLV2_API
 bool
 slv2_ui_supported(SLV2UI    ui,
                   SLV2Value widget_type_uri);
 
-/** Get the types (URIs of RDF classes) of a Plugin UI.
- * @param ui The Plugin UI
- * @return a shared value which must not be modified or freed.
- */
+/**
+   Get the types (URIs of RDF classes) of a Plugin UI.
+   @param ui The Plugin UI
+   @return a shared value which must not be modified or freed.
+*/
 SLV2_API
 SLV2Values
 slv2_ui_get_classes(SLV2UI ui);
 
-/** Check whether a plugin UI is a given type.
- * @param ui        The Plugin UI
- * @param class_uri The URI of the LV2 UI type to check this UI against
- */
+/**
+   Check whether a plugin UI is a given type.
+   @param ui        The Plugin UI
+   @param class_uri The URI of the LV2 UI type to check this UI against
+*/
 SLV2_API
 bool
 slv2_ui_is_a(SLV2UI ui, SLV2Value class_uri);
 
-/** Get the URI for a Plugin UI's bundle.
- * @param ui The Plugin UI
- * @return a shared value which must not be modified or freed.
- */
+/**
+   Get the URI for a Plugin UI's bundle.
+   @param ui The Plugin UI
+   @return a shared value which must not be modified or freed.
+*/
 SLV2_API
 SLV2Value
 slv2_ui_get_bundle_uri(SLV2UI ui);
 
-/** Get the URI for a Plugin UI's shared library.
- * @param ui The Plugin UI
- * @return a shared value which must not be modified or freed.
- */
+/**
+   Get the URI for a Plugin UI's shared library.
+   @param ui The Plugin UI
+   @return a shared value which must not be modified or freed.
+*/
 SLV2_API
 SLV2Value
 slv2_ui_get_binary_uri(SLV2UI ui);
 
-/** @} */
-/** @name Plugin UI Instance
- * @{
- */
+/**
+   @}
+   @name Plugin UI Instance
+   @{
+*/
 
 typedef struct _SLV2UIInstance* SLV2UIInstance;
 
-/** DEPRECATED: Instantiate a plugin UI.
- * This function is deprecated, it does not support widget wrapping.
- * Use @ref slv2_ui_instance_new instead.
- */
+/**
+   DEPRECATED: Instantiate a plugin UI.
+   This function is deprecated, it does not support widget wrapping.
+   Use @ref slv2_ui_instance_new instead.
+*/
 SLV2_DEPRECATED
 SLV2_API
 SLV2UIInstance
@@ -1181,16 +1298,17 @@ slv2_ui_instantiate(SLV2Plugin                plugin,
                     LV2UI_Controller          controller,
                     const LV2_Feature* const* features);
 
-/** Instantiate a plugin UI.
- * The returned object represents shared library objects loaded into memory,
- * it must be cleaned up with slv2_ui_instance_free when no longer
- * needed.
- *
- * @param features NULL-terminated array of features the host supports.
- *        NULL may be passed if the host supports no additional features.
- *
- * @return NULL if instantiation failed.
- */
+/**
+   Instantiate a plugin UI.
+   The returned object represents shared library objects loaded into memory,
+   it must be cleaned up with slv2_ui_instance_free when no longer
+   needed.
+ 
+   @param features NULL-terminated array of features the host supports.
+   NULL may be passed if the host supports no additional features.
+ 
+   @return NULL if instantiation failed.
+*/
 SLV2_API
 SLV2UIInstance
 slv2_ui_instance_new(SLV2Plugin                plugin,
@@ -1200,24 +1318,27 @@ slv2_ui_instance_new(SLV2Plugin                plugin,
                      LV2UI_Controller          controller,
                      const LV2_Feature* const* features);
 
-/** Free a plugin UI instance.
- * @a instance is invalid after this call.
- * It is the caller's responsibility to ensure all references to the UI
- * instance (including any returned widgets) are cut before calling
- * this function.
- */
+/**
+   Free a plugin UI instance.
+   @a instance is invalid after this call.
+   It is the caller's responsibility to ensure all references to the UI
+   instance (including any returned widgets) are cut before calling
+   this function.
+*/
 SLV2_API
 void
 slv2_ui_instance_free(SLV2UIInstance instance);
 
-/** Get the widget for the UI instance.
- */
+/**
+   Get the widget for the UI instance.
+*/
 SLV2_API
 LV2UI_Widget
 slv2_ui_instance_get_widget(SLV2UIInstance instance);
 
-/** Notify a UI about a change in a plugin port.
- */
+/**
+   Notify a UI about a change in a plugin port.
+*/
 SLV2_API
 void
 slv2_ui_instance_port_event(SLV2UIInstance instance,
@@ -1226,38 +1347,43 @@ slv2_ui_instance_port_event(SLV2UIInstance instance,
                             uint32_t       format,
                             const void*    buffer);
 
-/** Return a data structure defined by some LV2 extension URI.
- */
+/**
+   Return a data structure defined by some LV2 extension URI.
+*/
 SLV2_API
 const void*
 slv2_ui_instance_extension_data(SLV2UIInstance instance,
                                 const char*    uri);
 
-/** Get the LV2UI_Descriptor of the plugin UI instance.
- * Normally hosts should not need to access the LV2UI_Descriptor directly,
- * use the slv2_ui_instance_* functions.
- *
- * The returned descriptor is shared and must not be deleted.
- */
+/**
+   Get the LV2UI_Descriptor of the plugin UI instance.
+   Normally hosts should not need to access the LV2UI_Descriptor directly,
+   use the slv2_ui_instance_* functions.
+ 
+   The returned descriptor is shared and must not be deleted.
+*/
 SLV2_API
 const LV2UI_Descriptor*
 slv2_ui_instance_get_descriptor(SLV2UIInstance instance);
 
-/** Get the LV2UI_Handle of the plugin UI instance.
- * Normally hosts should not need to access the LV2UI_Handle directly,
- * use the slv2_ui_instance_* functions.
- *
- * The returned handle is shared and must not be deleted.
- */
+/**
+   Get the LV2UI_Handle of the plugin UI instance.
+   Normally hosts should not need to access the LV2UI_Handle directly,
+   use the slv2_ui_instance_* functions.
+ 
+   The returned handle is shared and must not be deleted.
+*/
 SLV2_API
 LV2UI_Handle
 slv2_ui_instance_get_handle(SLV2UIInstance instance);
 
-/** @} */
-/** @} */
+/**
+   @}
+   @}
+*/
 
 #ifdef __cplusplus
 } /* extern "C" */
 #endif
 
-#endif /* SLV2_SLV2_H__ */
+#endif /* SLV2_SLV2_H */