Update comments to standard style (no actual changes).

1 files changed, 222 insertions, 199 deletions

diff --git a/ext/event.lv2/event.h b/ext/event.lv2/event.h
index 7fb189c..9117723 100644
--- a/ext/event.lv2/event.h
+++ b/ext/event.lv2/event.h
@@ -1,22 +1,22 @@
-/* lv2_event.h - C header file for the LV2 events extension.
- *
- * Copyright (C) 2006-2007 Lars Luthman <lars.luthman@gmail.com>
- * Copyright (C) 2008-2009 David Robillard <http://drobilla.net>
- *
- * This header is free software; you can redistribute it and/or modify it
- * under the terms of the GNU Lesser General Public License as published
- * by the Free Software Foundation; either version 2 of the License, or
- * (at your option) any later version.
- *
- * This header is distributed in the hope that it will be useful, but WITHOUT
- * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
- * FITNESS FOR A PARTICULAR PURPOSE.  See the GNU Lesser General Public
- * License for more details.
- *
- * You should have received a copy of the GNU Lesser General Public License
- * along with this header; if not, write to the Free Software Foundation,
- * Inc., 59 Temple Place, Suite 330, Boston, MA 01222-1307 USA
- */
+/*
+  LV2 Event Extension
+  Copyright (C) 2006-2007 Lars Luthman <lars.luthman@gmail.com>
+  Copyright (C) 2008-2011 David Robillard <http://drobilla.net>
+ 
+  This header is free software; you can redistribute it and/or modify it
+  under the terms of the GNU Lesser General Public License as published
+  by the Free Software Foundation; either version 2 of the License, or
+  (at your option) any later version.
+ 
+  This header is distributed in the hope that it will be useful, but WITHOUT
+  ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
+  FITNESS FOR A PARTICULAR PURPOSE. See the GNU Lesser General Public
+  License for more details.
+ 
+  You should have received a copy of the GNU Lesser General Public License
+  along with this header; if not, write to the Free Software Foundation,
+  Inc., 59 Temple Place, Suite 330, Boston, MA 01222-1307 USA
+*/
 
 #ifndef LV2_EVENT_H
 #define LV2_EVENT_H
@@ -26,76 +26,80 @@
 
 #include <stdint.h>
 
-/** @file
- * C header for the LV2 Event extension <http://lv2plug.in/ns/ext/event>.
- *
- * This extension is a generic transport mechanism for time stamped events
- * of any type (e.g. MIDI, OSC, ramps, etc).  Each port can transport mixed
- * events of any type; the type of events and timestamps are defined by a URI
- * which is mapped to an integer by the host for performance reasons.
- *
- * This extension requires the host to support the LV2 URI Map extension.
- * Any host which supports this extension MUST guarantee that any call to
- * the LV2 URI Map uri_to_id function with the URI of this extension as the
- * 'map' argument returns a value within the range of uint16_t.
- */
-
-
-/** The best Pulses Per Quarter Note for tempo-based uint32_t timestmaps.
- * Equal to 2^12 * 5 * 7 * 9 * 11 * 13 * 17, which is evenly divisble
- * by all integers from 1 through 18 inclusive, and powers of 2 up to 2^12.
- */
+/**
+   @file event.h
+   C API for the LV2 Event extension <http://lv2plug.in/ns/ext/event>.
+ 
+   This extension is a generic transport mechanism for time stamped events
+   of any type (e.g. MIDI, OSC, ramps, etc). Each port can transport mixed
+   events of any type; the type of events and timestamps are defined by a URI
+   which is mapped to an integer by the host for performance reasons.
+ 
+   This extension requires the host to support the LV2 URI Map extension.
+   Any host which supports this extension MUST guarantee that any call to
+   the LV2 URI Map uri_to_id function with the URI of this extension as the
+   'map' argument returns a value within the range of uint16_t.
+*/
+
+/**
+   The best Pulses Per Quarter Note for tempo-based uint32_t timestmaps.
+   Equal to 2^12 * 5 * 7 * 9 * 11 * 13 * 17, which is evenly divisble
+   by all integers from 1 through 18 inclusive, and powers of 2 up to 2^12.
+*/
 static const uint32_t LV2_EVENT_PPQN = 3136573440U;
 
-
-/** An LV2 event (header only).
- *
- * LV2 events are generic time-stamped containers for any type of event.
- * The type field defines the format of a given event's contents.
- *
- * This struct defines the header of an LV2 event.  An LV2 event is a single
- * chunk of POD (plain old data), usually contained in a flat buffer
- * (see LV2_EventBuffer below).  Unless a required feature says otherwise,
- * hosts may assume a deep copy of an LV2 event can be created safely
- * using a simple:
- *
- * memcpy(ev_copy, ev, sizeof(LV2_Event) + ev->size);  (or equivalent)
- */
+/**
+   An LV2 event (header only).
+ 
+   LV2 events are generic time-stamped containers for any type of event.
+   The type field defines the format of a given event's contents.
+ 
+   This struct defines the header of an LV2 event. An LV2 event is a single
+   chunk of POD (plain old data), usually contained in a flat buffer (see
+   LV2_EventBuffer below). Unless a required feature says otherwise, hosts may
+   assume a deep copy of an LV2 event can be created safely using a simple:
+ 
+   memcpy(ev_copy, ev, sizeof(LV2_Event) + ev->size);  (or equivalent)
+*/
 typedef struct {
 
-	/** The frames portion of timestamp.  The units used here can optionally be
-	 * set for a port (with the lv2ev:timeUnits property), otherwise this
-	 * is audio frames, corresponding to the sample_count parameter of the
-	 * LV2 run method (e.g. frame 0 is the first frame for that call to run).
-	 */
+	/**
+	   The frames portion of timestamp. The units used here can optionally be
+	   set for a port (with the lv2ev:timeUnits property), otherwise this is
+	   audio frames, corresponding to the sample_count parameter of the LV2 run
+	   method (e.g. frame 0 is the first frame for that call to run).
+	*/
 	uint32_t frames;
 
-	/** The sub-frames portion of timestamp.  The units used here can
-	 * optionally be set for a port (with the lv2ev:timeUnits property),
-	 * otherwise this is 1/(2^32) of an audio frame.
-	 */
+	/**
+	   The sub-frames portion of timestamp. The units used here can optionally
+	   be set for a port (with the lv2ev:timeUnits property), otherwise this is
+	   1/(2^32) of an audio frame.
+	*/
 	uint32_t subframes;
 
-	/** The type of this event, as a number which represents some URI
-	 * defining an event type.  This value MUST be some value previously
-	 * returned from a call to the uri_to_id function defined in the LV2
-	 * URI map extension (see lv2_uri_map.h).
-	 * There are special rules which must be followed depending on the type
-	 * of an event.  If the plugin recognizes an event type, the definition
-	 * of that event type will describe how to interpret the event, and
-	 * any required behaviour.  Otherwise, if the type is 0, this event is a
-	 * non-POD event and lv2_event_unref MUST be called if the event is
-	 * 'dropped' (see above).  Even if the plugin does not understand an event,
-	 * it may pass the event through to an output by simply copying (and NOT
-	 * calling lv2_event_unref).  These rules are designed to allow for generic
-	 * event handling plugins and large non-POD events, but with minimal hassle
-	 * on simple plugins that "don't care" about these more advanced features.
-	 */
+	/**
+	   The type of this event, as a number which represents some URI
+	   defining an event type. This value MUST be some value previously
+	   returned from a call to the uri_to_id function defined in the LV2
+	   URI map extension (see lv2_uri_map.h).
+	   There are special rules which must be followed depending on the type
+	   of an event. If the plugin recognizes an event type, the definition
+	   of that event type will describe how to interpret the event, and
+	   any required behaviour. Otherwise, if the type is 0, this event is a
+	   non-POD event and lv2_event_unref MUST be called if the event is
+	   'dropped' (see above). Even if the plugin does not understand an event,
+	   it may pass the event through to an output by simply copying (and NOT
+	   calling lv2_event_unref). These rules are designed to allow for generic
+	   event handling plugins and large non-POD events, but with minimal hassle
+	   on simple plugins that "don't care" about these more advanced features.
+	*/
 	uint16_t type;
 
-	/** The size of the data portion of this event in bytes, which immediately
-	 * follows.  The header size (12 bytes) is not included in this value.
-	 */
+	/**
+	   The size of the data portion of this event in bytes, which immediately
+	   follows. The header size (12 bytes) is not included in this value.
+	*/
 	uint16_t size;
 
 	/* size bytes of data follow here */
@@ -103,152 +107,172 @@ typedef struct {
 } LV2_Event;
 
 
-
-/** A buffer of LV2 events (header only).
- *
- * Like events (which this contains) an event buffer is a single chunk of POD:
- * the entire buffer (including contents) can be copied with a single memcpy.
- * The first contained event begins sizeof(LV2_EventBuffer) bytes after
- * the start of this struct.
- *
- * After this header, the buffer contains an event header (defined by struct
- * LV2_Event), followed by that event's contents (padded to 64 bits), followed by
- * another header, etc:
- *
- * |       |       |       |       |       |       |
- * | | | | | | | | | | | | | | | | | | | | | | | | |
- * |FRAMES |SUBFRMS|TYP|LEN|DATA..DATA..PAD|FRAMES | ...
- */
+/**
+   A buffer of LV2 events (header only).
+ 
+   Like events (which this contains) an event buffer is a single chunk of POD:
+   the entire buffer (including contents) can be copied with a single memcpy.
+   The first contained event begins sizeof(LV2_EventBuffer) bytes after the
+   start of this struct.
+ 
+   After this header, the buffer contains an event header (defined by struct
+   LV2_Event), followed by that event's contents (padded to 64 bits), followed
+   by another header, etc:
+ 
+   |       |       |       |       |       |       |
+   | | | | | | | | | | | | | | | | | | | | | | | | |
+   |FRAMES |SUBFRMS|TYP|LEN|DATA..DATA..PAD|FRAMES | ...
+*/
 typedef struct {
 
-	/** The contents of the event buffer.  This may or may not reside in the
-	 * same block of memory as this header, plugins must not assume either.
-	 * The host guarantees this points to at least capacity bytes of allocated
-	 * memory (though only size bytes of that are valid events).
-	 */
+	/**
+	   The contents of the event buffer. This may or may not reside in the
+	   same block of memory as this header, plugins must not assume either.
+	   The host guarantees this points to at least capacity bytes of allocated
+	   memory (though only size bytes of that are valid events).
+	*/
 	uint8_t* data;
 
-	/** The size of this event header in bytes (including everything).
-	 *
-	 * This is to allow for extending this header in the future without
-	 * breaking binary compatibility.  Whenever this header is copied,
-	 * it MUST be done using this field (and NOT the sizeof this struct).
-	 */
+	/**
+	   The size of this event header in bytes (including everything).
+	 
+	   This is to allow for extending this header in the future without
+	   breaking binary compatibility. Whenever this header is copied,
+	   it MUST be done using this field (and NOT the sizeof this struct).
+	*/
 	uint16_t header_size;
 
-	/** The type of the time stamps for events in this buffer.
-	 * As a special exception, '0' always means audio frames and subframes
-	 * (1/UINT32_MAX'th of a frame) in the sample rate passed to instantiate.
-	 * INPUTS: The host must set this field to the numeric ID of some URI
-	 *     defining the meaning of the frames/subframes fields of contained
-	 *     events (obtained by the LV2 URI Map uri_to_id function with the URI
-	 *     of this extension as the 'map' argument, see lv2_uri_map.h).
-	 *     The host must never pass a plugin a buffer which uses a stamp type
-	 *     the plugin does not 'understand'.  The value of this field must
-	 *     never change, except when connect_port is called on the input
-	 *     port, at which time the host MUST have set the stamp_type field to
-	 *     the value that will be used for all subsequent run calls.
-	 * OUTPUTS: The plugin may set this to any value that has been returned
-	 *     from uri_to_id with the URI of this extension for a 'map' argument.
-	 *     When connected to a buffer with connect_port, output ports MUST set
-	 *     this field to the type of time stamp they will be writing.  On any
-	 *     call to connect_port on an event input port, the plugin may change
-	 *     this field on any output port, it is the responsibility of the host
-	 *     to check if any of these values have changed and act accordingly.
-	 */
+	/**
+	   The type of the time stamps for events in this buffer.
+	   As a special exception, '0' always means audio frames and subframes
+	   (1/UINT32_MAX'th of a frame) in the sample rate passed to instantiate.
+
+	   INPUTS: The host must set this field to the numeric ID of some URI
+	   defining the meaning of the frames/subframes fields of contained events
+	   (obtained by the LV2 URI Map uri_to_id function with the URI of this
+	   extension as the 'map' argument, see lv2_uri_map.h).  The host must
+	   never pass a plugin a buffer which uses a stamp type the plugin does not
+	   'understand'. The value of this field must never change, except when
+	   connect_port is called on the input port, at which time the host MUST
+	   have set the stamp_type field to the value that will be used for all
+	   subsequent run calls.
+	   
+	   OUTPUTS: The plugin may set this to any value that has been returned
+	   from uri_to_id with the URI of this extension for a 'map' argument.
+	   When connected to a buffer with connect_port, output ports MUST set this
+	   field to the type of time stamp they will be writing. On any call to
+	   connect_port on an event input port, the plugin may change this field on
+	   any output port, it is the responsibility of the host to check if any of
+	   these values have changed and act accordingly.
+	*/
 	uint16_t stamp_type;
 
-	/** The number of events in this buffer.
-	 * INPUTS: The host must set this field to the number of events
-	 *     contained in the data buffer before calling run().
-	 *     The plugin must not change this field.
-	 * OUTPUTS: The plugin must set this field to the number of events it
-	 *     has written to the buffer before returning from run().
-	 *     Any initial value should be ignored by the plugin.
-	 */
+	/**
+	   The number of events in this buffer.
+
+	   INPUTS: The host must set this field to the number of events contained
+	   in the data buffer before calling run(). The plugin must not change
+	   this field.
+
+	   OUTPUTS: The plugin must set this field to the number of events it has
+	   written to the buffer before returning from run(). Any initial value
+	   should be ignored by the plugin.
+	*/
 	uint32_t event_count;
 
-	/** The size of the data buffer in bytes.
-	 * This is set by the host and must not be changed by the plugin.
-	 * The host is allowed to change this between run() calls.
-	 */
+	/**
+	   The size of the data buffer in bytes.
+	   This is set by the host and must not be changed by the plugin.
+	   The host is allowed to change this between run() calls.
+	*/
 	uint32_t capacity;
 
-	/** The size of the initial portion of the data buffer containing data.
-	 * INPUTS: The host must set this field to the number of bytes used
-	 *     by all events it has written to the buffer (including headers)
-	 *     before calling the plugin's run().
-	 *     The plugin must not change this field.
-	 * OUTPUTS: The plugin must set this field to the number of bytes
-	 *     used by all events it has written to the buffer (including headers)
-	 *     before returning from run().
-	 *     Any initial value should be ignored by the plugin.
-	 */
+	/**
+	   The size of the initial portion of the data buffer containing data.
+
+	   INPUTS: The host must set this field to the number of bytes used
+	   by all events it has written to the buffer (including headers)
+	   before calling the plugin's run().
+	   The plugin must not change this field.
+
+	   OUTPUTS: The plugin must set this field to the number of bytes
+	   used by all events it has written to the buffer (including headers)
+	   before returning from run().
+	   Any initial value should be ignored by the plugin.
+	*/
 	uint32_t size;
 
 } LV2_Event_Buffer;
 
 
-/** Opaque pointer to host data. */
+/**
+   Opaque pointer to host data.
+*/
 typedef void* LV2_Event_Callback_Data;
 
 
-/** The data field of the LV2_Feature for this extension.
- *
- * To support this feature the host must pass an LV2_Feature struct to the
- * plugin's instantiate method with URI "http://lv2plug.in/ns/ext/event"
- * and data pointed to an instance of this struct.
- */
+/**
+   The data field of the LV2_Feature for this extension.
+ 
+   To support this feature the host must pass an LV2_Feature struct to the
+   plugin's instantiate method with URI "http://lv2plug.in/ns/ext/event"
+   and data pointed to an instance of this struct.
+*/
 typedef struct {
 
-	/** Opaque pointer to host data.
-	 *
-	 * The plugin MUST pass this to any call to functions in this struct.
-	 * Otherwise, it must not be interpreted in any way.
-	 */
+	/**
+	   Opaque pointer to host data.
+	 
+	   The plugin MUST pass this to any call to functions in this struct.
+	   Otherwise, it must not be interpreted in any way.
+	*/
 	LV2_Event_Callback_Data callback_data;
 
-	/** Take a reference to a non-POD event.
-	 *
-	 * If a plugin receives an event with type 0, it means the event is a
-	 * pointer to some object in memory and not a flat sequence of bytes
-	 * in the buffer.  When receiving a non-POD event, the plugin already
-	 * has an implicit reference to the event.  If the event is stored AND
-	 * passed to an output, lv2_event_ref MUST be called on that event.
-	 * If the event is only stored OR passed through, this is not necessary
-	 * (as the plugin already has 1 implicit reference).
-	 *
-	 * @param event An event received at an input that will not be copied to
-	 *              an output or stored in any way.
-	 * @param context The calling context.  (Like event types) this is a mapped
-	 *                URI, see lv2_context.h. Simple plugin with just a run()
-	 *                method should pass 0 here (the ID of the 'standard' LV2
-	 *                run context).  The host guarantees that this function is
-	 *                realtime safe iff @a context is realtime safe.
-	 *
-	 * PLUGINS THAT VIOLATE THESE RULES MAY CAUSE CRASHES AND MEMORY LEAKS.
-	 */
+	/**
+	   Take a reference to a non-POD event.
+	 
+	   If a plugin receives an event with type 0, it means the event is a
+	   pointer to some object in memory and not a flat sequence of bytes
+	   in the buffer. When receiving a non-POD event, the plugin already
+	   has an implicit reference to the event. If the event is stored AND
+	   passed to an output, lv2_event_ref MUST be called on that event.
+	   If the event is only stored OR passed through, this is not necessary
+	   (as the plugin already has 1 implicit reference).
+	 
+	   @param event An event received at an input that will not be copied to
+	   an output or stored in any way.
+	   
+	   @param context The calling context. Like event types, this is a mapped
+	   URI, see lv2_context.h. Simple plugin with just a run() method should
+	   pass 0 here (the ID of the 'standard' LV2 run context). The host
+	   guarantees that this function is realtime safe iff @a context is
+	   realtime safe.
+	 
+	   PLUGINS THAT VIOLATE THESE RULES MAY CAUSE CRASHES AND MEMORY LEAKS.
+	*/
 	uint32_t (*lv2_event_ref)(LV2_Event_Callback_Data callback_data,
 	                          LV2_Event*              event);
 
-	/** Drop a reference to a non-POD event.
-	 *
-	 * If a plugin receives an event with type 0, it means the event is a
-	 * pointer to some object in memory and not a flat sequence of bytes
-	 * in the buffer.  If the plugin does not pass the event through to
-	 * an output or store it internally somehow, it MUST call this function
-	 * on the event (more information on using non-POD events below).
-	 *
-	 * @param event An event received at an input that will not be copied to
-	 *              an output or stored in any way.
-	 * @param context The calling context.  (Like event types) this is a mapped
-	 *                URI, see lv2_context.h. Simple plugin with just a run()
-	 *                method should pass 0 here (the ID of the 'standard' LV2
-	 *                run context).  The host guarantees that this function is
-	 *                realtime safe iff @a context is realtime safe.
-	 *
-	 * PLUGINS THAT VIOLATE THESE RULES MAY CAUSE CRASHES AND MEMORY LEAKS.
-	 */
+	/**
+	   Drop a reference to a non-POD event.
+	 
+	   If a plugin receives an event with type 0, it means the event is a
+	   pointer to some object in memory and not a flat sequence of bytes
+	   in the buffer. If the plugin does not pass the event through to
+	   an output or store it internally somehow, it MUST call this function
+	   on the event (more information on using non-POD events below).
+	 
+	   @param event An event received at an input that will not be copied to an
+	   output or stored in any way.
+	   
+	   @param context The calling context. Like event types, this is a mapped
+	   URI, see lv2_context.h. Simple plugin with just a run() method should
+	   pass 0 here (the ID of the 'standard' LV2 run context). The host
+	   guarantees that this function is realtime safe iff @a context is
+	   realtime safe.
+	 
+	   PLUGINS THAT VIOLATE THESE RULES MAY CAUSE CRASHES AND MEMORY LEAKS.
+	*/
 	uint32_t (*lv2_event_unref)(LV2_Event_Callback_Data callback_data,
 	                            LV2_Event*              event);
 
@@ -256,4 +280,3 @@ typedef struct {
 
 
 #endif /* LV2_EVENT_H */
-