Improve documentation.

2 files changed, 31 insertions, 15 deletions

diff --git a/plugins/eg-amp.lv2/amp.c b/plugins/eg-amp.lv2/amp.c
index 344f7b4..189a697 100644
--- a/plugins/eg-amp.lv2/amp.c
+++ b/plugins/eg-amp.lv2/amp.c
@@ -40,12 +40,13 @@ typedef enum {
 
 /** Plugin instance. */
 typedef struct {
+	// Port buffers
 	float* gain;
 	float* input;
 	float* output;
 } Amp;
 
-/** Called to create a new plugin instance. */
+/** Create a new plugin instance. */
 static LV2_Handle
 instantiate(const LV2_Descriptor*     descriptor,
             double                    rate,
@@ -57,7 +58,7 @@ instantiate(const LV2_Descriptor*     descriptor,
 	return (LV2_Handle)amp;
 }
 
-/** Called to connect a port to a buffer (audio thread, must be RT safe). */
+/** Connect a port to a buffer (audio thread, must be RT safe). */
 static void
 connect_port(LV2_Handle instance,
              uint32_t   port,
@@ -78,7 +79,7 @@ connect_port(LV2_Handle instance,
 	}
 }
 
-/** Called to initialise and prepare the instance for running. */
+/** Initialise and prepare the plugin instance for running. */
 static void
 activate(LV2_Handle instance)
 {
@@ -87,7 +88,7 @@ activate(LV2_Handle instance)
 
 #define DB_CO(g) ((g) > -90.0f ? powf(10.0f, (g) * 0.05f) : 0.0f)
 
-/** Called to process a block of audio (audio thread, must be RT safe). */
+/** Process a block of audio (audio thread, must be RT safe). */
 static void
 run(LV2_Handle instance, uint32_t n_samples)
 {
@@ -104,21 +105,21 @@ run(LV2_Handle instance, uint32_t n_samples)
 	}
 }
 
-/** Called when running is finished (counterpart to activate()). */
+/** Finish running (counterpart to activate()). */
 static void
 deactivate(LV2_Handle instance)
 {
 	/* Nothing to do here in this trivial mostly stateless plugin. */
 }
 
-/** Called to destroy a plugin instance (counterpart to instantiate()). */
+/** Destroy a plugin instance (counterpart to instantiate()). */
 static void
 cleanup(LV2_Handle instance)
 {
 	free(instance);
 }
 
-/** Called to access extension data provided by the plugin. */
+/** Return extension data provided by the plugin. */
 const void*
 extension_data(const char* uri)
 {
diff --git a/plugins/eg-amp.lv2/manifest.ttl.in b/plugins/eg-amp.lv2/manifest.ttl.in
index 9d02b02..2813473 100644
--- a/plugins/eg-amp.lv2/manifest.ttl.in
+++ b/plugins/eg-amp.lv2/manifest.ttl.in
@@ -33,8 +33,13 @@
 
 # Explanation
 #
+# The token @LIB_EXT@ above is replaced by the build system (waf) by the
+# appropriate extension for the current platform (e.g. .so, .dylib, .dll),
+# which is why this file is called manifest.ttl.in and not manifest.ttl.  This
+# documentation assumes .so for simplicity.
+#
 # In short, this declares that the resource with URI
-# "http://lv2plug.in/plugins/eg-amp") is an LV2 plugin, with executable code in
+# "http://lv2plug.in/plugins/eg-amp" is an LV2 plugin, with executable code in
 # the file "amp.so" and a full description in "amp.ttl".  These paths are
 # relative to the bundle directory.
 #
@@ -46,17 +51,19 @@
 # 2 | <http://lv2plug.in/plugins/eg-amp>  | lv2:binary   | <amp.so>
 # 3 | <http://lv2plug.in/plugins/eg-amp>  | rdfs:seeAlso | <amp.ttl>
 #
-# The semicolon is used to continue the previous subject, an equivalent
+# The semicolon is used to continue the previous subject; an equivalent
 # but more verbose syntax for the same data is:
-#
-# <http://lv2plug.in/plugins/eg-amp> a lv2:Plugin .
-# <http://lv2plug.in/plugins/eg-amp> lv2:binary <amp.so> .
-# <http://lv2plug.in/plugins/eg-amp> rdfs:seeAlso <amp.ttl> .
+
+<http://lv2plug.in/plugins/eg-amp> a lv2:Plugin .
+<http://lv2plug.in/plugins/eg-amp> lv2:binary <amp.so> .
+<http://lv2plug.in/plugins/eg-amp> rdfs:seeAlso <amp.ttl> .
+
+# (Since this data is equivalent, it is safe, if pointless, to list it twice)
 #
 # Note that the documentation for a URI can often be found by visiting that URI
 # in a web browser, e.g. the documentation for lv2:binary can be found at
-# <http://lv2plug.in/ns/lv2core#binary>.  If you encounter a predicate in some
-# data which you do not understand, try this first.
+# <http://lv2plug.in/ns/lv2core#binary>.  If you encounter a URI in some data
+# which you do not understand, try this first.
 #
 # Note the URI of a plugin does NOT need to be an actual web address, it's just
 # a global identifier.  It is, however, a good idea to use an actual web
@@ -64,6 +71,14 @@
 # downloads, etc.  Note there are compatibility rules for when the URI of a
 # plugin must be changed, see the LV2 specification[4] for details.
 #
+# AUTHORS MUST NOT CREATE URIS AT DOMAINS THEY DO NOT CONTROL WITHOUT
+# PERMISSION, AND *ESPECIALLY* MUST NOT CREATE SYNTACTICALLY INVALID URIS,
+# E.G. WHERE THE PORTION FOLLOWING "http://" IS NOT AN ACTUAL DOMAIN NAME.  If
+# you need an example URI, the domain http://example.org/ is reserved for this
+# purpose.  It is best to use web URIs, e.g. at the domain where plugins are
+# hosted for download, even if there is currently no documents hosted there.
+# If this is truly impossible, use a URN, e.g. urn:myplugs:superamp.
+#
 # A detailed explanation of each statement follows.
 #
 # 1: <http://lv2plug.in/plugins/eg-amp> a lv2:Plugin