Rewrite and clean up some documentation.

1 files changed, 34 insertions, 55 deletions

diff --git a/core.lv2/lv2.h b/core.lv2/lv2.h
index 4e8d225..ce55d45 100644
--- a/core.lv2/lv2.h
+++ b/core.lv2/lv2.h
@@ -34,24 +34,21 @@ extern "C" {
 #endif
 
 /**
-   Plugin Handle.
+   Plugin Instance Handle.
  
-   This handle refers to a particular instance of a plugin. It is valid to
+   This is a handle for one particular instance of a plugin.  It is valid to
    compare to NULL (or 0 for C++) but otherwise the host MUST NOT attempt to
-   interpret it. The plugin may use it to reference internal instance data.
+   interpret it.
 */
 typedef void * LV2_Handle;
 
 /**
    Feature.
  
-   Features are used to provide an extensible interface to allow adding
-   arbitrary functionality to implementations without breaking API
-   compatibility. In particular, they may be passed by the host to the plugin's
-   instantiate method to provide additional functionality. Extensions that
-   describe a feature MUST specify the @a URI and format of @a data that needs
-   to be used here. The core LV2 specification does not define any features;
-   implementations are not required to use this facility.
+   Features allow hosts to make additional functionality available to plugins
+   without requiring modification to the LV2 API.  Extensions may define new
+   features and specify the @ref URI and @ref data to be used if necessary.
+   Some features, such as lv2:isLive, do not require the host to pass data.
 */
 typedef struct _LV2_Feature {
 	/**
@@ -65,27 +62,24 @@ typedef struct _LV2_Feature {
 	   Pointer to arbitrary data.
 
 	   The format of this data is defined by the extension which describes the
-	   feature with the given @a URI. The core LV2 specification makes no
-	   restrictions on the format of this data. If no data is required, this
-	   may be set to NULL if the relevant extension explicitly allows this.
+	   feature with the given @ref URI.
 	*/
 	void * data;
 } LV2_Feature;
 
 /**
-   Descriptor for an LV2 Plugin.
+   Plugin Descriptor.
  
-   This structure is used to describe a plugin. It provides the functions
-   necessary to instantiate and use a plugin.
+   This structure provides the core functions necessary to instantiate and use
+   a plugin.
 */
 typedef struct _LV2_Descriptor {
 	/**
 	   A globally unique, case-sensitive identifier for this plugin.
 
-	   This MUST be a valid URI string as defined by RFC 3986. All plugins with
-	   the same URI are compatible to some degree; see lv2.ttl and the <a
-	   href="http://lv2plug.in/ns/lv2core">LV2 Ontology Documentation</a> for
-	   details.
+	   This MUST be a valid URI string as defined by RFC 3986.  All plugins with
+	   the same URI MUST be compatible to some degree, see
+	   http://lv2plug.in/ns/lv2core for details.
 	*/
 	const char * URI;
 
@@ -194,12 +188,12 @@ typedef struct _LV2_Descriptor {
 	   things that the plugin MUST NOT do within the run() function (see
 	   lv2.ttl for details).
 
-	   As a special case, when @a sample_count == 0, the plugin should update
+	   As a special case, when @c sample_count == 0, the plugin should update
 	   any output ports that represent a single instant in time (e.g. control
 	   ports, but not audio ports). This is particularly useful for latent
 	   plugins, which should update their latency output port so hosts can
 	   pre-roll plugins to compute latency. Plugins MUST NOT crash when
-	   @a sample_count == 0.
+	   @c sample_count == 0.
 
 	   @param instance Instance to be run.
 
@@ -249,21 +243,11 @@ typedef struct _LV2_Descriptor {
 	   pointers to extend the LV2_Descriptor API.
 	 
 	   The actual type and meaning of the returned object MUST be specified
-	   precisely by the extension if it defines any extra data. This function
-	   MUST return NULL for any unsupported URI. If a plugin does not support
-	   any extension data, this field may be NULL.
-	 
-	   @param uri URI of the extension. The plugin MUST return NULL if it does
-	   not support the extension, but hosts MUST NOT use this as a discovery
-	   mechanism. Hosts should only call this function for extensions known to
-	   be supported by the plugin, as described in the plugin's RDF data.
+	   precisely by the extension. This function MUST return NULL for any
+	   unsupported URI. If a plugin does not support any extension data, this
+	   field may be NULL.
 	 
 	   The host is never responsible for freeing the returned value.
-	 
-	   Note this function SHOULD return a struct (likely containing function
-	   pointers) and NOT a direct function pointer. Casting void* to a function
-	   pointer type is not portable, and returning a struct is much safer
-	   since it is extensible (fields can be added without breaking the ABI).
 	*/
 	const void * (*extension_data)(const char * uri);
 } LV2_Descriptor;
@@ -271,28 +255,23 @@ typedef struct _LV2_Descriptor {
 /**
    Prototype for plugin accessor function.
  
-   The exact mechanism by which plugin libraries are loaded is host and system
-   dependent, however all hosts need to know is the URI of the plugin they wish
-   to load. Plugins are discovered via RDF data (not by loading plugin
-   libraries). Documentation on best practices for plugin discovery can be
-   found at <http://lv2plug.in>, however it is expected that hosts use a
-   library to provide this functionality.
- 
+   Plugins are discovered by hosts using RDF data (not by loading libraries).
+   See http://lv2plug.in for details on the discovery process, though most
+   hosts should use an existing library to implement this functionality.
+
    A plugin library MUST include a function called "lv2_descriptor" with this
-   prototype. This function MUST have C-style linkage (if you are using C++
+   prototype.  This function MUST have C-style linkage (if you are using C++
    this is taken care of by the 'extern "C"' clause at the top of this file).
- 
-   A host will find the plugin's library via RDF data, get the lv2_descriptor()
-   function from it, and proceed from there.
- 
-   Plugins are accessed by index using values from 0 upwards. Out of range
-   indices MUST result in this function returning NULL, so the host can
-   enumerate plugins by increasing @a index until NULL is returned.
-
-   Note that @a index has no meaning, hosts MUST NOT depend on it remaining
-   constant in any way. In other words, @a index is NOT a plugin ID.  In
-   particular, hosts MUST NOT refer to plugins by library path and index in
-   persistent serialisations (e.g. save files).
+
+   When it is time to load a plugin (designated by its URI), the host loads the
+   plugin's library, gets the lv2_descriptor() function from it, and uses this
+   function to find the LV2_Descriptor for the desired plugin.  Plugins are
+   accessed by index using values from 0 upwards.  This function MUST return
+   NULL for out of range indices, so the host can enumerate plugins by
+   increasing @c index until NULL is returned.
+
+   Note that @c index has no meaning, hosts MUST NOT depend on it remaining
+   consistent between loads of the plugin library.
 */
 const LV2_Descriptor * lv2_descriptor(uint32_t index);