Rewrite and clean up some documentation.

3 files changed, 49 insertions, 77 deletions

diff --git a/core.lv2/ChangeLog b/core.lv2/ChangeLog
index 2a86606..643b2cf 100644
--- a/core.lv2/ChangeLog
+++ b/core.lv2/ChangeLog
@@ -3,7 +3,7 @@ lv2core (UNRELEASED) unstable; urgency=low
   * Remove lv2config in favour of the convention that extension bundles simply
     install headers to standard URI-like include paths
   * Switch to simple BSD-style (ISC) license (with permission of all
-    contributors to lv2.h and it's ancestor, ladspa.h)
+    contributors to lv2.h and its ancestor, ladspa.h)
 
  -- David Robillard <d@drobilla.net>  UNRELEASED
 
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);
 
diff --git a/core.lv2/lv2.ttl b/core.lv2/lv2.ttl
index f77a2c4..d18c865 100644
--- a/core.lv2/lv2.ttl
+++ b/core.lv2/lv2.ttl
@@ -97,12 +97,11 @@ Code, data, and any other resources (e.g. waveforms) are shipped together in a
 <q>bundle</q> directory.  The code contains only the executable portions of the
 plugin which inherently <em>must</em> be written in code.  All other data is
 provided in the data file(s).  This makes plugin data flexible and extensible,
-and allows the host to do everything but run the plugin without executing any
-code at all.  Among other advantages, this makes hosts more robust (broken
-plugins can't crash a host during discovery) and allows non-C programs to work
-with LV2 data (such as the pure <a href="http://python.org">Python</a> script
-which generated this page).  LV2 itself and extensions are distributed
-similarly.</p>
+and allows the host to do everything but run the plugin without loading or
+executing any code.  Among other advantages, this makes hosts more robust
+(broken plugins can't crash a host during discovery) and allows generic tools
+and non-C programs to work with LV2 data.  LV2 itself and extensions are
+distributed in a similar way.</p>
 
 <p>An LV2 plugin library is suitable for dynamic loading (e.g. via
 <code>dlopen()</code>) and provides one or more <a
@@ -132,21 +131,15 @@ controlled by the host (and not necessarily constant).</p>
 into several threading classes:</p>
 
 <table>
-<tr>
-  <th>Discovery Class</th>
-  <th>Instantiation Class</th>
-  <th>Audio Class</th>
-</tr>
-<tr>
-  <td>lv2_descriptor()</td>
-  <td>LV2_Descriptor::instantiate()</td>
-  <td>LV2_Descriptor::run()</td>
-</tr>
-<tr>
-  <td>LV2_Descriptor::extension_data()</td>
-  <td>LV2_Descriptor::cleanup()</td>
-  <td>LV2_Descriptor::connect_port()</td>
-</tr>
+<tr><th>Discovery Class</th>
+    <th>Instantiation Class</th>
+    <th>Audio Class</th></tr>
+<tr><td>lv2_descriptor()</td>
+    <td>LV2_Descriptor::instantiate()</td>
+    <td>LV2_Descriptor::run()</td></tr>
+<tr><td>LV2_Descriptor::extension_data()</td>
+    <td>LV2_Descriptor::cleanup()</td>
+    <td>LV2_Descriptor::connect_port()</td></tr>
 <tr><td></td><td>LV2_Descriptor::activate()</td><td></td></tr>
 <tr><td></td><td>LV2_Descriptor::deactivate()</td><td></td></tr>
 </table>