Improve documentation.

4 files changed, 39 insertions, 25 deletions

diff --git a/lv2/lv2plug.in/ns/lv2core/lv2.h b/lv2/lv2plug.in/ns/lv2core/lv2.h
index 220fbb0..6e0edaa 100644
--- a/lv2/lv2plug.in/ns/lv2core/lv2.h
+++ b/lv2/lv2plug.in/ns/lv2core/lv2.h
@@ -353,19 +353,15 @@ typedef struct _LV2_Descriptor {
 /**
    Prototype for plugin accessor function.
 
-   This is part of the old discovery API, which has been replaced due to being
-   inadequate for some plugins.  It is limited because the bundle path is not
-   available during discovery, and it relies on non-portable shared library
-   constructors/destructors.  However, this API is still supported and plugins
-   are not required to migrate.
-
    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++
-   this is taken care of by the 'extern "C"' clause at the top of this file).
+   This is the simple plugin discovery API, suitable for most statically
+   defined plugins.  Advanced plugins that need access to their bundle during
+   discovery can use lv2_lib_descriptor() instead.  Plugin libraries MUST
+   include a function called "lv2_descriptor" or "lv2_lib_descriptor" with
+   C-style linkage, but SHOULD provide "lv2_descriptor" wherever possible.
 
    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
@@ -431,6 +427,13 @@ typedef struct {
 /**
    Prototype for library accessor function.
 
+   This is the more advanced discovery API, which allows plugin libraries to
+   access their bundles during discovery, which makes it possible for plugins to
+   be dynamically defined by files in their bundle.  This API also has an
+   explicit cleanup function, removing any need for non-portable shared library
+   destructors.  Simple plugins that do not require these features may use
+   lv2_descriptor() instead.
+
    This is the entry point for a plugin library.  Hosts load this symbol from
    the library and call this function to obtain a library descriptor which can
    be used to access all the contained plugins.  The returned object must not
diff --git a/lv2/lv2plug.in/ns/lv2core/lv2core.doap.ttl b/lv2/lv2plug.in/ns/lv2core/lv2core.doap.ttl
index df919b6..273a2f9 100644
--- a/lv2/lv2plug.in/ns/lv2core/lv2core.doap.ttl
+++ b/lv2/lv2plug.in/ns/lv2core/lv2core.doap.ttl
@@ -16,6 +16,15 @@
 		<http://drobilla.net/drobilla#me> ;
 	doap:maintainer <http://drobilla.net/drobilla#me> ;
 	doap:release [
+		doap:revision "12.1" ;
+		doap:created "2014-04-26" ;
+		dcs:blame <http://drobilla.net/drobilla#me> ;
+		dcs:changeset [
+			dcs:item [
+				rdfs:label "Clarify lv2_descriptor() and lv2_lib_descriptor() documentation."
+			]
+		]
+	] , [
 		doap:revision "12.0" ;
 		doap:created "2014-01-04" ;
 		doap:file-release <http://lv2plug.in/spec/lv2-1.8.0.tar.bz2> ;
diff --git a/lv2/lv2plug.in/ns/lv2core/lv2core.ttl b/lv2/lv2plug.in/ns/lv2core/lv2core.ttl
index 7fbffd4..b48b4ca 100644
--- a/lv2/lv2plug.in/ns/lv2core/lv2core.ttl
+++ b/lv2/lv2plug.in/ns/lv2core/lv2core.ttl
@@ -61,10 +61,10 @@ 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 plugin descriptors via the
-<code>lv2_descriptor()</code> function.  These can be instantiated to create
-plugin <q>instances</q>, which can be run directly on data or connected
-together to perform advanced signal processing tasks.</p>
+<code>dlopen()</code>) and provides one or more plugin descriptors via
+<code>lv2_descriptor()</code> or <code>lv2_lib_descriptor()</code>.  These can
+be instantiated to create plugin <q>instances</q>, which can be run directly on
+data or connected together to perform advanced signal processing tasks.</p>
 
 <p>Plugins communicate via <q>ports</q>, which can transmit any type of data.
 Data is processed by first <q>connecting</q> each port to a buffer, then
@@ -92,10 +92,11 @@ into several threading classes:</p>
 <tr><td>lv2_descriptor()</td>
     <td>LV2_Descriptor::instantiate()</td>
     <td>LV2_Descriptor::run()</td></tr>
-<tr><td>LV2_Descriptor::extension_data()</td>
+<tr><td>lv2_lib_descriptor()</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>LV2_Descriptor::extension_data()</td>
+    <td>LV2_Descriptor::activate()</td><td></td></tr>
 <tr><td></td><td>LV2_Descriptor::deactivate()</td><td></td></tr>
 </table>
 
@@ -416,10 +417,11 @@ resolves to a shared library object (the actual type of this library is system
 specific).</p>
 
 <p>This is a required property of a Plugin which MUST be included in the
-bundle's manifest.ttl file. The lv2:binary of an lv2:Plugin is the
-shared object containing the <code>lv2_descriptor()</code> function which can
-be used to access the descriptor for that plugin. This property may be used
-similarly by extensions to relate other resources to their implementations.</p>
+bundle's manifest.ttl file. The lv2:binary of an lv2:Plugin is the shared
+object containing the <code>lv2_descriptor()</code> or
+<code>lv2_lib_descriptor()</code> function which can be used to access the
+descriptor for that plugin. This property may be used similarly by extensions
+to relate other resources to their implementations.</p>
 """ .
 
 lv2:appliesTo
@@ -688,10 +690,10 @@ lv2:ExtensionData
 	a rdfs:Class ,
 		owl:Class ;
 	rdfs:label "Extension Data" ;
-	rdfs:comment """
-Additional data and/or functions a plugin may return from
-LV2_Descriptor:extension_data() which can be used to add additional API beyond
-that defined by LV2_Descriptor.
+	lv2:documentation """
+<p>Additional data and/or functions a plugin may return from
+LV2_Descriptor::extension_data() which can be used to add additional API beyond
+that defined by LV2_Descriptor.</p>
 """ .
 
 lv2:extensionData
@@ -701,7 +703,7 @@ lv2:extensionData
 	rdfs:label "extension data" ;
 	lv2:documentation """
 <p>Signifies that a plugin provides additional data or functions (as defined by
-some extension) via LV2:Descriptor::instantiate().</p>
+some extension) via LV2_Descriptor::instantiate().</p>
 """ .
 
 lv2:isLive
diff --git a/lv2/lv2plug.in/ns/lv2core/manifest.ttl b/lv2/lv2plug.in/ns/lv2core/manifest.ttl
index 6e1c389..fcced8c 100644
--- a/lv2/lv2plug.in/ns/lv2core/manifest.ttl
+++ b/lv2/lv2plug.in/ns/lv2core/manifest.ttl
@@ -5,5 +5,5 @@
 <http://lv2plug.in/ns/lv2core>
 	a lv2:Specification ;
 	lv2:minorVersion 12 ;
-	lv2:microVersion 0 ;
+	lv2:microVersion 1 ;
 	rdfs:seeAlso <lv2core.ttl> .