Add initial WIP for more user friendly docs

See May 2018 lv2-devel discussion for some of the motivations
for the different style of documentation.

2 files changed, 27 insertions, 4 deletions

diff --git a/plugins/eg-amp.lv2/amp.c b/plugins/eg-amp.lv2/amp.c
index c3ba279..433a9d4 100644
--- a/plugins/eg-amp.lv2/amp.c
+++ b/plugins/eg-amp.lv2/amp.c
@@ -36,17 +36,21 @@
    file is a good convention to follow.  If this URI does not match that used
    in the data files, the host will fail to load the plugin.
 */
+// tag::AMP_URI[]
 #define AMP_URI "http://lv2plug.in/plugins/eg-amp"
+// end::AMP_URI[]
 
 /**
    In code, ports are referred to by index.  An enumeration of port indices
    should be defined for readability.
 */
+// tag::PortIndex[]
 typedef enum {
 	AMP_GAIN   = 0,
 	AMP_INPUT  = 1,
 	AMP_OUTPUT = 2
 } PortIndex;
+// end::PortIndex[]
 
 /**
    Every plugin defines a private structure for the plugin instance.  All data
@@ -54,12 +58,13 @@ typedef enum {
    every instance method.  In this simple plugin, only port buffers need to be
    stored, since there is no additional instance data.
 */
+// tag::Amp[]
 typedef struct {
-	// Port buffers
-	const float* gain;
-	const float* input;
-	float*       output;
+	const float* gain;   // Gain control input
+	const float* input;  // Audio input
+	float*       output; // Audio output
 } Amp;
+// end::Amp[]
 
 /**
    The `instantiate()` function is called by the host to create a new plugin
@@ -71,6 +76,7 @@ typedef struct {
    This function is in the ``instantiation'' threading class, so no other
    methods on this instance will be called concurrently with it.
 */
+// tag::instantiate[]
 static LV2_Handle
 instantiate(const LV2_Descriptor*     descriptor,
             double                    rate,
@@ -81,6 +87,7 @@ instantiate(const LV2_Descriptor*     descriptor,
 
 	return (LV2_Handle)amp;
 }
+// end::instantiate[]
 
 /**
    The `connect_port()` method is called by the host to connect a particular
@@ -90,6 +97,7 @@ instantiate(const LV2_Descriptor*     descriptor,
    This method is in the ``audio'' threading class, and is called in the same
    context as run().
 */
+// tag::connect_port[]
 static void
 connect_port(LV2_Handle instance,
              uint32_t   port,
@@ -109,6 +117,7 @@ connect_port(LV2_Handle instance,
 		break;
 	}
 }
+// end::connect_port[]
 
 /**
    The `activate()` method is called by the host to initialise and prepare the
@@ -124,6 +133,8 @@ activate(LV2_Handle instance)
 {
 }
 
+// tag::run[]
+
 /** Define a macro for converting a gain in dB to a coefficient. */
 #define DB_CO(g) ((g) > -90.0f ? powf(10.0f, (g) * 0.05f) : 0.0f)
 
@@ -149,6 +160,8 @@ run(LV2_Handle instance, uint32_t n_samples)
 	}
 }
 
+// end::run[]
+
 /**
    The `deactivate()` method is the counterpart to `activate()`, and is called by
    the host after running the plugin.  It indicates that the host will not call
@@ -171,11 +184,13 @@ deactivate(LV2_Handle instance)
    This method is in the ``instantiation'' threading class, so no other
    methods on this instance will be called concurrently with it.
 */
+// tag::cleanup[]
 static void
 cleanup(LV2_Handle instance)
 {
 	free(instance);
 }
+// end::cleanup[]
 
 /**
    The `extension_data()` function returns any extension data supported by the
@@ -193,6 +208,8 @@ extension_data(const char* uri)
 	return NULL;
 }
 
+// tag::descriptor[]
+
 /**
    Every plugin must define an `LV2_Descriptor`.  It is best to define
    descriptors statically to avoid leaking memory and non-portable shared
@@ -228,3 +245,5 @@ lv2_descriptor(uint32_t index)
 	default: return NULL;
 	}
 }
+
+// end::descriptor[]
diff --git a/plugins/eg-amp.lv2/amp.ttl b/plugins/eg-amp.lv2/amp.ttl
index 9f522a1..87fd76a 100644
--- a/plugins/eg-amp.lv2/amp.ttl
+++ b/plugins/eg-amp.lv2/amp.ttl
@@ -2,11 +2,13 @@
 # `manifest.ttl`.  This is done so the host only needs to scan the relatively
 # small `manifest.ttl` files to quickly discover all plugins.
 
+# tag::prefixes[]
 @prefix doap:  <http://usefulinc.com/ns/doap#> .
 @prefix lv2:   <http://lv2plug.in/ns/lv2core#> .
 @prefix rdf:   <http://www.w3.org/1999/02/22-rdf-syntax-ns#> .
 @prefix rdfs:  <http://www.w3.org/2000/01/rdf-schema#> .
 @prefix units: <http://lv2plug.in/ns/extensions/units#> .
+# end::prefixes[]
 
 # First the type of the plugin is described.  All plugins must explicitly list
 # `lv2:Plugin` as a type.  A more specific type should also be given, where
@@ -36,6 +38,7 @@
 		"Просто Усилитель"@ru ;
 	doap:license <http://opensource.org/licenses/isc> ;
 	lv2:optionalFeature lv2:hardRTCapable ;
+# tag::ports[]
 	lv2:port [
 # Every port must have at least two types, one that specifies direction
 # (lv2:InputPort or lv2:OutputPort), and another to describe the data type.
@@ -88,3 +91,4 @@
 		lv2:symbol "out" ;
 		lv2:name "Out"
 	] .
+# end::ports[]