From 301a6f2267a795420a6e8bd3d7ea814670a02bfd Mon Sep 17 00:00:00 2001 From: David Robillard Date: Thu, 14 Jun 2012 21:09:39 +0000 Subject: Improve documentation. --- plugins/eg-amp.lv2/amp.c | 15 ++++++++------- plugins/eg-amp.lv2/manifest.ttl.in | 31 +++++++++++++++++++++++-------- 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 | | lv2:binary | # 3 | | rdfs:seeAlso | # -# 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: -# -# a lv2:Plugin . -# lv2:binary . -# rdfs:seeAlso . + + a lv2:Plugin . + lv2:binary . + rdfs:seeAlso . + +# (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 -# . If you encounter a predicate in some -# data which you do not understand, try this first. +# . 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: a lv2:Plugin -- cgit v1.2.1