same

source/includes/lv2/lv2.h

@@ -19,9 +19,11 @@
 */
 
 /**
-   @file lv2.h
-   API for the LV2 specification <http://lv2plug.in/ns/lv2core>.
-   Revision: 12.0
+   @defgroup lv2core LV2 Core
+
+   Core LV2 specification, see <http://lv2plug.in/ns/lv2core> for details.
+
+   @{
 */
 
 #ifndef LV2_H_INCLUDED
@@ -135,7 +137,7 @@ typedef void * LV2_Handle;
 
    Features allow hosts to make additional functionality available to plugins
    without requiring modification to the LV2 API.  Extensions may define new
-   features and specify the @ref URI and @ref data to be used if necessary.
+   features and specify the `URI` and `data` to be used if necessary.
    Some features, such as lv2:isLive, do not require the host to pass data.
 */
 typedef struct _LV2_Feature {
@@ -150,7 +152,7 @@ typedef struct _LV2_Feature {
 	   Pointer to arbitrary data.
 
 	   The format of this data is defined by the extension which describes the
-	   feature with the given @ref URI.
+	   feature with the given `URI`.
 	*/
 	void * data;
 } LV2_Feature;
@@ -276,12 +278,12 @@ typedef struct _LV2_Descriptor {
 	   things that the plugin MUST NOT do within the run() function (see
 	   lv2core.ttl for details).
 
-	   As a special case, when @p sample_count == 0, the plugin should update
+	   As a special case, when `sample_count` is 0, the plugin should update
 	   any output ports that represent a single instant in time (e.g. control
 	   ports, but not audio ports). This is particularly useful for latent
 	   plugins, which should update their latency output port so hosts can
 	   pre-roll plugins to compute latency. Plugins MUST NOT crash when
-	   @p sample_count == 0.
+	   `sample_count` is 0.
 
 	   @param instance Instance to be run.
 
@@ -340,14 +342,23 @@ typedef struct _LV2_Descriptor {
 	const void * (*extension_data)(const char * uri);
 } LV2_Descriptor;
 
+/**
+   Helper macro needed for LV2_SYMBOL_EXPORT when using C++.
+*/
+#ifdef __cplusplus
+#    define LV2_SYMBOL_EXTERN extern "C"
+#else
+#    define LV2_SYMBOL_EXTERN
+#endif
+
 /**
    Put this (LV2_SYMBOL_EXPORT) before any functions that are to be loaded
    by the host as a symbol from the dynamic library.
 */
 #ifdef _WIN32
-#    define LV2_SYMBOL_EXPORT __declspec(dllexport)
+#    define LV2_SYMBOL_EXPORT LV2_SYMBOL_EXTERN __declspec(dllexport)
 #else
-#    define LV2_SYMBOL_EXPORT
+#    define LV2_SYMBOL_EXPORT LV2_SYMBOL_EXTERN __attribute__((visibility("default")))
 #endif
 
 /**
@@ -368,9 +379,9 @@ typedef struct _LV2_Descriptor {
    function to find the LV2_Descriptor for the desired plugin.  Plugins are
    accessed by index using values from 0 upwards.  This function MUST return
    NULL for out of range indices, so the host can enumerate plugins by
-   increasing @p index until NULL is returned.
+   increasing `index` until NULL is returned.
 
-   Note that @p index has no meaning, hosts MUST NOT depend on it remaining
+   Note that `index` has no meaning, hosts MUST NOT depend on it remaining
    consistent between loads of the plugin library.
 */
 LV2_SYMBOL_EXPORT
@@ -418,7 +429,7 @@ typedef struct {
 
 	   Plugins are accessed by index using values from 0 upwards.  Out of range
 	   indices MUST result in this function returning NULL, so the host can
-	   enumerate plugins by increasing @a index until NULL is returned.
+	   enumerate plugins by increasing `index` until NULL is returned.
 	*/
 	const LV2_Descriptor * (*get_plugin)(LV2_Lib_Handle handle,
 	                                     uint32_t       index);
@@ -440,6 +451,7 @@ typedef struct {
    be destroyed (using LV2_Lib_Descriptor::cleanup()) until all plugins loaded
    from that library have been destroyed.
 */
+LV2_SYMBOL_EXPORT
 const LV2_Lib_Descriptor *
 lv2_lib_descriptor(const char *               bundle_path,
                    const LV2_Feature *const * features);
@@ -456,3 +468,7 @@ typedef const LV2_Lib_Descriptor *
 #endif
 
 #endif /* LV2_H_INCLUDED */
+
+/**
+   @}
+*/

source/includes/lv2/ui.h

@@ -17,9 +17,12 @@
 */
 
 /**
-   @file ui.h User Interface API.
+   @defgroup ui User Interfaces
 
-   For high-level documentation, see <http://lv2plug.in/ns/extensions/ui>.
+   User interfaces of any type for plugins,
+   <http://lv2plug.in/ns/extensions/ui> for details.
+
+   @{
 */
 
 #ifndef LV2_UI_H
@@ -37,6 +40,7 @@
 #define LV2_UI__GtkUI            LV2_UI_PREFIX "GtkUI"
 #define LV2_UI__PortNotification LV2_UI_PREFIX "PortNotification"
 #define LV2_UI__Qt4UI            LV2_UI_PREFIX "Qt4UI"
+#define LV2_UI__Qt5UI            LV2_UI_PREFIX "Qt5UI"
 #define LV2_UI__UI               LV2_UI_PREFIX "UI"
 #define LV2_UI__WindowsUI        LV2_UI_PREFIX "WindowsUI"
 #define LV2_UI__X11UI            LV2_UI_PREFIX "X11UI"
@@ -59,7 +63,7 @@
 #define LV2_UI__windowTitle      LV2_UI_PREFIX "windowTitle"
 
 /**
-   The index returned by LV2_UI_Port_Port::port_index() for unknown ports.
+   The index returned by LV2UI_Port_Map::port_index() for unknown ports.
 */
 #define LV2UI_INVALID_PORT_INDEX ((uint32_t)-1)
 
@@ -98,18 +102,21 @@ typedef void* LV2UI_Feature_Handle;
 /**
    A host-provided function that sends data to a plugin's input ports.
 
-   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.
+   @param controller The opaque controller pointer passed to
+   LV2UI_Descriptor::instantiate().
+
+   @param port_index Index of the port to update.
 
-   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, @p buffer MUST point to a single
-   float value, and @p buffer_size MUST be sizeof(float).
+   @param buffer Buffer containing `buffer_size` bytes of data.
 
-   The UI SHOULD NOT use a protocol not supported by the host, but the host
-   MUST gracefully ignore any protocol it does not understand.
+   @param buffer_size Size of `buffer` in bytes.
+
+   @param port_protocol Either 0 or the URID for a ui:PortProtocol.  If 0, the
+   protocol is implicitly ui:floatProtocol, the port MUST be an lv2:ControlPort
+   input, `buffer` MUST point to a single float value, and `buffer_size` MUST
+   be sizeof(float).  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,
@@ -143,7 +150,7 @@ typedef struct _LV2UI_Descriptor {
 	   @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 to be passed as the
+	   @param controller A handle for the UI instance to be passed as the
 	   first parameter of UI methods.
 
 	   @param widget (output) widget pointer.  The UI points this at its main
@@ -173,18 +180,18 @@ typedef struct _LV2UI_Descriptor {
 	/**
 	   Tell the UI that something interesting has happened at a plugin port.
 
-	   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().
+	   What is "interesting" and how it is written to `buffer` is defined by
+	   `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
+	   every change), `buffer_size` must be sizeof(float), and `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
+	   The UI MUST NOT retain any reference to `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.
@@ -201,7 +208,7 @@ typedef struct _LV2UI_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;
@@ -247,7 +254,7 @@ typedef struct _LV2UI_Port_Map {
 	LV2UI_Feature_Handle handle;
 
 	/**
-	   Get the index for the port with the given @p symbol.
+	   Get the index for the port with the given `symbol`.
 
 	   @return The index of the port, or LV2UI_INVALID_PORT_INDEX if no such
 	   port is found.
@@ -271,7 +278,7 @@ typedef struct _LV2UI_Port_Subscribe {
 	   This means that the host will call the UI's port_event() function when
 	   the port value changes (as defined by protocol).
 
-	   Calling this function with the same @p port_index and @p port_protocol
+	   Calling this function with the same `port_index` and `port_protocol`
 	   as an already active subscription has no effect.
 
 	   @param handle The handle field of this struct.
@@ -291,7 +298,7 @@ typedef struct _LV2UI_Port_Subscribe {
 	   This means that the host will cease calling calling port_event() when
 	   the port value changes.
 
-	   Calling this function with a @p port_index and @p port_protocol that
+	   Calling this function with a `port_index` and `port_protocol` that
 	   does not refer to an active port subscription has no effect.
 
 	   @param handle The handle field of this struct.
@@ -428,3 +435,7 @@ typedef const LV2UI_Descriptor* (*LV2UI_DescriptorFunction)(uint32_t index);
 #endif
 
 #endif /* LV2_UI_H */
+
+/**
+   @}
+*/

source/includes/lv2/worker.h

@@ -15,8 +15,12 @@
 */
 
 /**
-   @file worker.h C header for the LV2 Worker extension
-   <http://lv2plug.in/ns/ext/worker>.
+   @defgroup worker Worker
+
+   Support for non-realtime plugin operations, see
+   <http://lv2plug.in/ns/ext/worker> for details.
+
+   @{
 */
 
 #ifndef LV2_WORKER_H
@@ -37,7 +41,7 @@ extern "C" {
 #endif
 
 /**
-   A status code for worker functions.
+   Status code for worker functions.
 */
 typedef enum {
 	LV2_WORKER_SUCCESS       = 0,  /**< Completed successfully. */
@@ -45,12 +49,13 @@ typedef enum {
 	LV2_WORKER_ERR_NO_SPACE  = 2   /**< Failed due to lack of space. */
 } LV2_Worker_Status;
 
+/** Opaque handle for LV2_Worker_Interface::work(). */
 typedef void* LV2_Worker_Respond_Handle;
 
 /**
    A function to respond to run() from the worker method.
 
-   The @p data MUST be safe for the host to copy and later pass to
+   The `data` MUST be safe for the host to copy and later pass to
    work_response(), and the host MUST guarantee that it will be eventually
    passed to work_response() if this function returns LV2_WORKER_SUCCESS.
 */
@@ -60,7 +65,7 @@ typedef LV2_Worker_Status (*LV2_Worker_Respond_Function)(
 	const void*               data);
 
 /**
-   LV2 Plugin Worker Interface.
+   Plugin Worker Interface.
 
    This is the interface provided by the plugin to implement a worker method.
    The plugin's extension_data() method should return an LV2_Worker_Interface
@@ -71,14 +76,14 @@ typedef struct _LV2_Worker_Interface {
 	   The worker method.  This is called by the host in a non-realtime context
 	   as requested, possibly with an arbitrary message to handle.
 
-	   A response can be sent to run() using @p respond.  The plugin MUST NOT
+	   A response can be sent to run() using `respond`.  The plugin MUST NOT
 	   make any assumptions about which thread calls this method, other than
 	   the fact that there are no real-time requirements.
 
 	   @param instance The LV2 instance this is a method on.
 	   @param respond  A function for sending a response to run().
-	   @param handle   Must be passed to @p respond if it is called.
-	   @param size     The size of @p data.
+	   @param handle   Must be passed to `respond` if it is called.
+	   @param size     The size of `data`.
 	   @param data     Data from run(), or NULL.
 	*/
 	LV2_Worker_Status (*work)(LV2_Handle                  instance,
@@ -92,7 +97,7 @@ typedef struct _LV2_Worker_Interface {
 	   run() context when a response from the worker is ready.
 
 	   @param instance The LV2 instance this is a method on.
-	   @param size     The size of @p body.
+	   @param size     The size of `body`.
 	   @param body     Message body, or NULL.
 	*/
 	LV2_Worker_Status (*work_response)(LV2_Handle  instance,
@@ -112,8 +117,15 @@ typedef struct _LV2_Worker_Interface {
 	LV2_Worker_Status (*end_run)(LV2_Handle instance);
 } LV2_Worker_Interface;
 
+/** Opaque handle for LV2_Worker_Schedule. */
 typedef void* LV2_Worker_Schedule_Handle;
 
+/**
+   Schedule Worker Host Feature.
+
+   The host passes this feature to provide a schedule_work() function, which
+   the plugin can use to schedule a worker call from run().
+*/
 typedef struct _LV2_Worker_Schedule {
 	/**
 	   Opaque host data.
@@ -138,12 +150,12 @@ typedef struct _LV2_Worker_Schedule {
 	   immediately, and responses from the worker are delivered immediately,
 	   the effect of the work takes place immediately with sample accuracy.
 
-	   The @p data MUST be safe for the host to copy and later pass to work(),
+	   The `data` MUST be safe for the host to copy and later pass to work(),
 	   and the host MUST guarantee that it will be eventually passed to work()
 	   if this function returns LV2_WORKER_SUCCESS.
 
 	   @param handle The handle field of this struct.
-	   @param size   The size of @p data.
+	   @param size   The size of `data`.
 	   @param data   Message to pass to work(), or NULL.
 	*/
 	LV2_Worker_Status (*schedule_work)(LV2_Worker_Schedule_Handle handle,
@@ -156,3 +168,7 @@ typedef struct _LV2_Worker_Schedule {
 #endif
 
 #endif  /* LV2_WORKER_H */
+
+/**
+   @}
+*/