Improve documentation.

3 files changed, 103 insertions, 107 deletions

diff --git a/lv2/lv2plug.in/ns/extensions/ui/lv2-ui.doap.ttl b/lv2/lv2plug.in/ns/extensions/ui/lv2-ui.doap.ttl
index 2abb648..24397c3 100644
--- a/lv2/lv2plug.in/ns/extensions/ui/lv2-ui.doap.ttl
+++ b/lv2/lv2plug.in/ns/extensions/ui/lv2-ui.doap.ttl
@@ -8,7 +8,7 @@
 	rdfs:seeAlso <../../meta/meta.ttl> ;
 	doap:license <http://opensource.org/licenses/isc> ;
 	doap:name "LV2 UI" ;
-	doap:shortdesc "Generic UI interface for LV2 plugins." ;
+	doap:shortdesc "LV2 plugin UIs of any type." ;
 	doap:created "2006-00-00" ;
 	doap:developer <http://lv2plug.in/ns/meta#larsl> ;
 	doap:maintainer <http://drobilla.net/drobilla#me> ;
diff --git a/lv2/lv2plug.in/ns/extensions/ui/ui.h b/lv2/lv2plug.in/ns/extensions/ui/ui.h
index e59e298..9eaa75c 100644
--- a/lv2/lv2plug.in/ns/extensions/ui/ui.h
+++ b/lv2/lv2plug.in/ns/extensions/ui/ui.h
@@ -1,6 +1,6 @@
 /*
   LV2 UI Extension
-  Copyright 2009-2013 David Robillard <d@drobilla.net>
+  Copyright 2009-2014 David Robillard <d@drobilla.net>
   Copyright 2006-2011 Lars Luthman <lars.luthman@gmail.com>
 
   Permission to use, copy, modify, and/or distribute this software for any
@@ -17,8 +17,9 @@
 */
 
 /**
-   @file ui.h
-   C header for the LV2 UI extension <http://lv2plug.in/ns/extensions/ui>.
+   @file ui.h User Interface API
+
+   For high-level documentation, see <http://lv2plug.in/ns/extensions/ui>.
 */
 
 #ifndef LV2_UI_H
@@ -75,20 +76,16 @@ extern "C" {
 typedef void* LV2UI_Widget;
 
 /**
-   A pointer to an instance of a UI.
+   A pointer to UI instance internals.
 
-   It is valid to compare this to NULL (0 for C++) but otherwise the host MUST
-   not attempt to interpret it.  The UI plugin may use it to reference internal
-   instance data.
+   The host may compare this to NULL, but otherwise MUST NOT interpret it.
 */
 typedef void* LV2UI_Handle;
 
 /**
    A pointer to a controller provided by the host.
 
-   It is valid to compare this to NULL (0 for C++) but otherwise the UI plugin
-   MUST NOT attempt to interpret it.  The host may use it to reference internal
-   instance data.
+   The UI may compare this to NULL, but otherwise MUST NOT interpret it.
 */
 typedef void* LV2UI_Controller;
 
@@ -98,22 +95,20 @@ typedef void* LV2UI_Controller;
 typedef void* LV2UI_Feature_Handle;
 
 /**
-   The type of the host-provided function that the UI can use to
-   send data to a plugin's input ports.
+   A host-provided function that sends data to a plugin's input ports.
 
-   The @p buffer parameter must point to a block of data, @c buffer_size bytes
+   The @p buffer parameter must point to a block of data, @p buffer_size bytes
    large.  The format of this data and how the host should use it is defined by
    the @p port_protocol.  This buffer is owned by the UI and is only valid for
    the duration of this call.
 
    The @p port_protocol parameter should either be 0 or the URID for a
    ui:PortProtocol.  If it is 0, the protocol is implicitly ui:floatProtocol,
-   the port must be an lv2:ControlPort input, @c buffer must point to a single
-   float value, and @c buffer_size must be sizeof(float).
+   the port MUST be an lv2:ControlPort input, @p buffer MUST point to a single
+   float value, and @p buffer_size MUST be sizeof(float).
 
-   The UI SHOULD NOT use a PortProtocol not supported by the host (i.e. one not
-   passed by the host as a feature), but the host MUST gracefully ignore any
-   port_protocol it does not understand.
+   The UI SHOULD NOT use a protocol not supported by the host, but the host
+   MUST gracefully ignore any protocol it does not understand.
 */
 typedef void (*LV2UI_Write_Function)(LV2UI_Controller controller,
                                      uint32_t         port_index,
@@ -122,7 +117,7 @@ typedef void (*LV2UI_Write_Function)(LV2UI_Controller controller,
                                      const void*      buffer);
 
 /**
-   The implementation of a UI.
+   A plugin UI.
 
    A pointer to an object of this type is returned by the lv2ui_descriptor()
    function.
@@ -134,32 +129,29 @@ typedef struct _LV2UI_Descriptor {
 	const char* URI;
 
 	/**
-	   Create a new UI object and return a handle to it.  This function works
-	   similarly to the instantiate() member in LV2_Descriptor.
+	   Create a new UI and return a handle to it.  This function works
+	   similarly to LV2_Descriptor::instantiate().
 
-	   @param descriptor The descriptor for the UI that you want to instantiate.
+	   @param descriptor The descriptor for the UI to instantiate.
 
 	   @param plugin_uri The URI of the plugin that this UI will control.
 
-	   @param bundle_path The path to the bundle containing the RDF data file
-	   that references this shared object file, including the trailing '/'.
+	   @param bundle_path The path to the bundle containing this UI, including
+	   the trailing directory separator.
 
-	   @param write_function A function provided by the host that the UI can use
-	   to send data to the plugin's input ports.
+	   @param write_function A function that the UI can use to send data to the
+	   plugin's input ports.
 
-	   @param controller A handle for the plugin instance that should be passed
-	   as the first parameter of @p write_function.
+	   @param controller A handle for the plugin instance to be passed as the
+	   first parameter of UI methods.
 
-	   @param widget A pointer to an LV2UI_Widget.  The UI will write a widget
-	   pointer to this location (what type of widget depends on the RDF class of
-	   the UI) that will be the main UI widget.
+	   @param widget (output) widget pointer.  The UI points this at its main
+	   widget, which has the type defined by the UI type in the data file.
 
-	   @param features An array of LV2_Feature pointers.  The host must pass all
-	   feature URIs that it and the UI supports and any additional data, just
-	   like in the LV2 plugin instantiate() function.  Note that UI features and
-	   plugin features are NOT necessarily the same, they just share the same
-	   data structure - this will probably not be the same array as the one the
-	   plugin host passes to a plugin.
+	   @param features An array of LV2_Feature pointers.  The host must pass
+	   all feature URIs that it and the UI supports and any additional data, as
+	   in LV2_Descriptor::instantiate().  Note that UI features and plugin
+	   features are not necessarily the same.
 
 	*/
 	LV2UI_Handle (*instantiate)(const struct _LV2UI_Descriptor* descriptor,
@@ -172,33 +164,29 @@ typedef struct _LV2UI_Descriptor {
 
 
 	/**
-	   Destroy the UI object and the associated widget. The host must not try
-	   to access the widget after calling this function.
+	   Destroy the UI.  The host must not try to access the widget after
+	   calling this function.
 	*/
 	void (*cleanup)(LV2UI_Handle ui);
 
 	/**
 	   Tell the UI that something interesting has happened at a plugin port.
 
-	   What is interesting and how it is written to the buffer passed to this
-	   function is defined by the @p format parameter, which has the same
-	   meaning as in LV2UI_Write_Function.  The only exception is ports of the
-	   class lv2:ControlPort, for which this function should be called when the
-	   port value changes (it does not have to be called for every single change
-	   if the host's UI thread has problems keeping up with the thread the
-	   plugin is running in), @p buffer_size should be 4, the buffer should
-	   contain a single IEEE-754 float, and @p format should be 0.
-
-	   By default, the host should only call this function for input ports of
-	   the lv2:ControlPort class.  However, this can be modified by using
-	   ui:portNotification in the UI data, or the ui:portSubscribe feature.
-
-	   The @p buffer is only valid during the time of this function call, so if
-	   the UI wants to keep it for later use it has to copy the contents to an
-	   internal buffer.
-
-	   This member may be set to NULL if the UI is not interested in any
-	   port events.
+	   What is "interesting" and how it is written to @p buffer is defined by
+	   @p format, which has the same meaning as in LV2UI_Write_Function().
+	   Format 0 is a special case for lv2:ControlPort, where this function
+	   should be called when the port value changes (but not necessarily for
+	   every change), @p buffer_size must be sizeof(float), and @p buffer
+	   points to a single IEEE-754 float.
+
+	   By default, the host should only call this function for lv2:ControlPort
+	   inputs.  However, the UI can request updates for other ports statically
+	   with ui:portNotification or dynamicaly with ui:portSubscribe.
+
+	   The UI MUST NOT retain any reference to @p buffer after this function
+	   returns, it is only valid for the duration of the call.
+
+	   This member may be NULL if the UI is not interested in any port events.
 	*/
 	void (*port_event)(LV2UI_Handle ui,
 	                   uint32_t     port_index,
@@ -207,22 +195,21 @@ typedef struct _LV2UI_Descriptor {
 	                   const void*  buffer);
 
 	/**
-	   Return a data structure associated with an extension URI, for example
-	   a struct containing additional function pointers.
+	   Return a data structure associated with an extension URI, typically an
+	   interface struct with additional function pointers
 
-	   Avoid returning function pointers directly since standard C/C++ has no
-	   valid way of casting a void* to a function pointer. This member may be set
-	   to NULL if the UI is not interested in supporting any extensions. This is
-	   similar to the extension_data() member in LV2_Descriptor.
+	   This member may be set to NULL if the UI is not interested in supporting
+	   any extensions. This is similar to LV2_Descriptor::extension_data().
+	   
 	*/
 	const void* (*extension_data)(const char* uri);
 } LV2UI_Descriptor;
 
 /**
-   UI Resize Feature (LV2_UI__resize)
+   Feature/interface for resizable UIs (LV2_UI__resize).
 
-   This structure may be used in two ways: as a feature passed by the host via
-   LV2UI_Descriptor::instantiate(), or as extension data provided by a UI via
+   This structure is used in two ways: as a feature passed by the host via
+   LV2UI_Descriptor::instantiate(), or as an interface provided by a UI via
    LV2UI_Descriptor::extension_data()).
 */
 typedef struct _LV2UI_Resize {
@@ -232,13 +219,13 @@ typedef struct _LV2UI_Resize {
 	LV2UI_Feature_Handle handle;
 
 	/**
-	   Request or advertise a size change.
+	   Request/advertise a size change.
 
-	   When this struct is provided by the host, the UI may call this
-	   function to inform the host about the size of the UI.
+	   When provided by the host, the UI may call this function to inform the
+	   host about the size of the UI.
 
-	   When this struct is provided by the UI, the host may call this
-	   function to notify the UI that it should change its size accordingly.
+	   When provided by the UI, the host may call this function to notify the
+	   UI that it should change its size accordingly.
 
 	   @return 0 on success.
 	*/
@@ -246,16 +233,15 @@ typedef struct _LV2UI_Resize {
 } LV2UI_Resize;
 
 /**
-   Port Map Feature (LV2_UI__portMap).
+   Feature to map port symbols to UIs.
 
-   This feature can be used by the UI to get the index for a port with the
-   given symbol.  This makes it possible to implement and distribute a UI
-   separately from the plugin (since symbol is a guaranteed stable port
-   identifier while index is not).
+   This can be used by the UI to get the index for a port with the given
+   symbol.  This makes it possible to implement and distribute a UI separately
+   from the plugin (since symbol, unlike index, is a stable port identifier).
 */
 typedef struct _LV2UI_Port_Map {
 	/**
-	   Pointer to opaque data which must be passed to ui_resize().
+	   Pointer to opaque data which must be passed to port_index().
 	*/
 	LV2UI_Feature_Handle handle;
 
@@ -269,11 +255,12 @@ typedef struct _LV2UI_Port_Map {
 } LV2UI_Port_Map;
 
 /**
-   Port subscription feature (LV2_UI__portSubscribe);
+   Feature to subscribe to port updates (LV2_UI__portSubscribe).
 */
 typedef struct _LV2UI_Port_Subscribe {
 	/**
-	   Pointer to opaque data which must be passed to ui_resize().
+	   Pointer to opaque data which must be passed to subscribe() and
+	   unsubscribe().
 	*/
 	LV2UI_Feature_Handle handle;
 
@@ -319,7 +306,7 @@ typedef struct _LV2UI_Port_Subscribe {
 } LV2UI_Port_Subscribe;
 
 /**
-   A feature to notify the host the user has grabbed a UI control.
+   A feature to notify the host that the user has grabbed a UI control.
 */
 typedef struct _LV2UI_Touch {
 	/**
@@ -330,6 +317,9 @@ typedef struct _LV2UI_Touch {
 	/**
 	   Notify the host that a control has been grabbed or released.
 
+	   The host should cease automating the port or otherwise manipulating the
+	   port value until the control has been ungrabbed.
+
 	   @param handle The handle field of this struct.
 	   @param port_index The index of the port associated with the control.
 	   @param grabbed If true, the control has been grabbed, otherwise the
@@ -341,19 +331,23 @@ typedef struct _LV2UI_Touch {
 } LV2UI_Touch;
 
 /**
-   UI Idle Feature (LV2_UI__idleInterface)
+   UI Idle Interface (LV2_UI__idleInterface)
 
-   This feature is an addition to the UI API that provides a callback for the
-   host to call rapidly, e.g. to drive the idle callback of a toolkit.
+   UIs can provide this interface to have an idle() callback called by the host
+   rapidly to update the UI.
 */
 typedef struct _LV2UI_Idle_Interface {
 	/**
 	   Run a single iteration of the UI's idle loop.
 
-	   This will be called "frequently" in the UI thread at a rate appropriate
-	   for a toolkit main loop.  There are no precise timing guarantees.
+	   This will be called rapidly in the UI thread at a rate appropriate
+	   for a toolkit main loop.  There are no precise timing guarantees, but
+	   the host should attempt to call idle() at a high enough rate for smooth
+	   animation, at least 30Hz.
 
-	   @return 0 on success, or anything else to stop being called.
+	   @return non-zero if the UI has been closed, in which case the host
+	   should stop calling idle(), and can either completely destroy the UI, or
+	   re-show it and resume calling idle().
 	*/
 	int (*idle)(LV2UI_Handle ui);
 } LV2UI_Idle_Interface;
@@ -361,11 +355,15 @@ typedef struct _LV2UI_Idle_Interface {
 /**
    UI Show Interface (LV2_UI__showInterface)
 
-   UIs can use this interface to provide show/hide methods to pop up a window,
-   which allows them to function in hosts unable to embed their widget type.
+   UIs can provide this interface to show and hide a window, which allows them
+   to function in hosts unable to embed their widget.  This allows any UI to
+   provide a fallback for embedding that works in any host.
 
-   If used, LV2UI_Idle_Interface should also be used to drive the UI.  The UI
-   should return non-zero from idle() when the window has been closed.
+   If used:
+   - The host MUST use LV2UI_Idle_Interface to drive the UI.
+   - The UI MUST return non-zero from LV2UI_Idle_Interface::idle() when it has been closed.
+   - If idle() returns non-zero, the host MUST call hide() and stop calling
+     idle().  It MAY later call show() then resume calling idle().
 */
 typedef struct _LV2UI_Show_Interface {
 	/**
@@ -407,17 +405,10 @@ typedef struct _LV2UI_Peak_Data {
 } LV2UI_Peak_Data;
 
 /**
-   A plugin UI programmer must include a function called "lv2ui_descriptor"
-   with the following function prototype within the shared object file.  This
-   function will have C-style linkage (if you are using C++ this is taken care
-   of by the 'extern "C"' clause at the top of the file).  This function is
-   loaded from the library by the UI host and called to get a
-   LV2UI_Descriptor for the wanted plugin.
-
-   Just like lv2_descriptor(), this function takes an index parameter.  The
-   index should only be used for enumeration and not as any sort of ID number -
-   the host should just iterate from 0 and upwards until the function returns
-   NULL or a descriptor with an URI matching the one the host is looking for.
+   Prototype for UI accessor function.
+
+   This is the entry point to a UI library, which works in the same way as
+   lv2_descriptor() but for UIs rather than plugins.
 */
 LV2_SYMBOL_EXPORT
 const LV2UI_Descriptor* lv2ui_descriptor(uint32_t index);
diff --git a/lv2/lv2plug.in/ns/extensions/ui/ui.ttl b/lv2/lv2plug.in/ns/extensions/ui/ui.ttl
index c8aa10a..9fb19c9 100644
--- a/lv2/lv2plug.in/ns/extensions/ui/ui.ttl
+++ b/lv2/lv2plug.in/ns/extensions/ui/ui.ttl
@@ -11,10 +11,15 @@
 	rdfs:seeAlso <ui.h> ,
 		<lv2-ui.doap.ttl> ;
 	lv2:documentation """
-<p>This extension defines an interface that can be used in LV2 plugins and
-hosts to create UIs for plugins. The UIs are similar to plugins and reside in
-shared object files in an LV2 bundle.  UIs are associated with a plugin in RDF
-using the triples:</p>
+    
+<p>This extension is used to create User Interfaces (UIs) for LV2 plugins.</p>
+
+<p>UIs are implemented as an LV2UI_Descriptor loaded via lv2ui_descriptor() in
+a shared library, and are distributed in bundles just like plugins.  See the <a
+href="../../../doc/html/ui_8h.html">API reference</a> for details on the C
+API.</p>
+
+<p>UIs are associated with plugins in data:</p>
 
 <pre class="turtle-code">
 @prefix ui: &lt;http://lv2plug.in/ns/extensions/ui#&gt; .