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.

1 files changed, 23 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[]