Tidy up documentation, remove cruft.

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

1 files changed, 20 insertions, 135 deletions

diff --git a/slv2/plugin.h b/slv2/plugin.h
index e936bf4..f688626 100644
--- a/slv2/plugin.h
+++ b/slv2/plugin.h
@@ -29,7 +29,7 @@ extern "C" {
 #include "slv2/port.h"
 #include "slv2/collections.h"
 
-/** \defgroup slv2_data Plugin data access
+/** @defgroup slv2_data Plugin data access
  *
  * These functions work exclusively with the plugin's RDF data,
  * they do not access the plugin's shared library in any way.
@@ -42,25 +42,19 @@ extern "C" {
  */
 
 /** Check if this plugin is valid.
- *
- * This is used by plugin lists to avoid loading plugins that are not valid
- * and will not work with libslv2 (eg plugins missing required fields, or
- * having multiple values for mandatory single-valued fields, etc.
+ * 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 if \a plugin is valid.
- *
- * Time = Query
+ * @return true iff @a plugin is valid.
  */
 SLV2_API
 bool
 slv2_plugin_verify(SLV2Plugin plugin);
 
-/** Get the URI of \a 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.
@@ -71,70 +65,51 @@ slv2_plugin_verify(SLV2Plugin 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 string which must not be modified or free()'d.
- *
- * Time = O(1)
+ * @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 plugins "main" bundle.
- *
+/** 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 returns URIs which are not below this one.
+ * 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.
- *
- * Time = O(1)
+ * @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",
+ * @return a list of complete URLs eg. "file:///foo/ABundle.lv2/aplug.ttl",
  * which is shared and must not be modified or freed.
- *
- * Time = O(1)
  */
 SLV2_API
 SLV2Values
 slv2_plugin_get_data_uris(SLV2Plugin plugin);
 
-/** Get the (resolvable) URI of the shared library for \a 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.
- *
- * Time = O(1)
+ * @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.
- *
+/** 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.
- *
- * Time = Query
  */
 SLV2_API
 SLV2Value
@@ -147,6 +122,7 @@ 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:
  *
@@ -154,13 +130,7 @@ slv2_plugin_get_class(SLV2Plugin plugin);
  *
  * 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.
- *
- * \a predicate must be either a URI or a QName.
- * See SLV2URIType documentation for examples.
- *
- * Time = Query
  */
 SLV2_API
 SLV2Values
@@ -168,7 +138,6 @@ 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.
@@ -179,6 +148,7 @@ 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:
  *
@@ -189,13 +159,7 @@ slv2_plugin_get_value_by_qname(SLV2Plugin  p,
  *
  * May return NULL if the property was not found, or if object is not
  * sensibly represented as an SLV2Values (e.g. blank nodes).
- *
- * \a predicate must be either a URI or a QName.
- * See SLV2URIType documentation for examples.
- *
  * Return value must be freed by caller with slv2_values_free.
- *
- * Time = Query
  */
 SLV2_API
 SLV2Values
@@ -204,11 +168,8 @@ slv2_plugin_get_value_for_subject(SLV2Plugin p,
                                   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.
- *
- * Time = Query
  */
 SLV2_API
 bool
@@ -216,7 +177,6 @@ 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
@@ -224,15 +184,12 @@ slv2_plugin_has_feature(SLV2Plugin p,
  * and slv2_plugin_get_required_features separately is best in most cases.
  *
  * Returned value must be freed by caller with slv2_values_free.
- *
- * Time = Query
  */
 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.
  *
@@ -241,38 +198,30 @@ slv2_plugin_get_supported_features(SLV2Plugin p);
  * or plugin instantiation will fail.
  *
  * Return value must be freed by caller with slv2_values_free.
- *
- * Time = Query
  */
 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.
- *
- * Time = Query
  */
 SLV2_API
 SLV2Values
 slv2_plugin_get_optional_features(SLV2Plugin p);
 
 /** Get the number of ports on this plugin.
- *
- * Time = O(1)
  */
 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
+ * @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,
@@ -292,12 +241,9 @@ slv2_plugin_get_port_ranges_float(SLV2Plugin p,
                                   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.
- *
- * Time = O(1)
  */
 SLV2_API
 uint32_t
@@ -305,82 +251,35 @@ 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.
- *
- * Time = Query
  */
 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.
- *
- * Time = Query
  */
 SLV2_API
 uint32_t
 slv2_plugin_get_latency_port_index(SLV2Plugin p);
 
-/** Query a plugin for a single variable (i.e. SELECT a single ?value).
- *
- * \param plugin The plugin to query.
- * \param sparql_str A SPARQL SELECT query.
- * \param variable The index of the variable to return results for
- *        (e.g. with "<code>SELECT ?foo ?bar</code>" foo=0, bar=1).
- * \return All matches for \a variable.
- *
- * Time = Query
- */
-SLV2_API
-SLV2Values
-slv2_plugin_query_variable(SLV2Plugin  plugin,
-                           const char* sparql_str,
-                           unsigned    variable);
-
-/** Query a plugin and return the number of results found.
- *
- * Note that this function will work, but is mostly meaningless for queries
- * that are not SELECT DISTINCT.
- *
- * \param plugin The plugin to query.
- * \param sparql_str A SPARQL SELECT DISTINCT query.
- *
- * Time = Query
- */
-SLV2_API
-unsigned
-slv2_plugin_query_count(SLV2Plugin  plugin,
-                        const char* sparql_str);
-
-/** Get a port on this plugin by \a index.
- *
- * To perform multiple calls on a port, the returned value should
- * be cached and used repeatedly.
- *
- * Time = O(1)
+/** 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 this plugin by \a symbol.
- *
- * To perform multiple calls on a port, the returned value should
- * be cached and used repeatedly.  Note this function is slower
- * than slv2_plugin_get_port_by_index, especially on plugins
- * with a very large number of ports.
- *
- * Time = O(n)
+/** 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
@@ -388,49 +287,35 @@ slv2_plugin_get_port_by_symbol(SLV2Plugin plugin,
                                SLV2Value  symbol);
 
 /** Get a list of all UIs available for this plugin.
- *
  * Note this returns the URI of the UI, and not the path/URI to its shared
  * library, use slv2_ui_get_library_uri with the values returned
  * here for that.
  *
  * Returned value must be freed by caller using slv2_uis_free.
- *
- * \param plugin The plugin to get the UIs for.
- *
- * Time = Query
  */
 SLV2_API
 SLV2UIs
 slv2_plugin_get_uis(SLV2Plugin plugin);
 
 /** Get the full name of the plugin's author.
- *
  * Returns NULL if author name is not present.
  * Returned value must be freed by caller.
- *
- * Time = Query
  */
 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.
- *
- * Time = Query
  */
 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.
- *
- * Time = Query
  */
 SLV2_API
 SLV2Value