Use standard style (no functional changes).

1 files changed, 154 insertions, 144 deletions

diff --git a/ext/persist.lv2/persist.h b/ext/persist.lv2/persist.h
index 2ac4880..0a8f4f0 100644
--- a/ext/persist.lv2/persist.h
+++ b/ext/persist.lv2/persist.h
@@ -1,24 +1,26 @@
-/* lv2_persist.h - C header file for the LV2 Persist extension.
- * Copyright (C) 2010 Leonard Ritter <paniq@paniq.org>
- *
- * 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
- */
+/*
+  Copyright (C) 2010-2011 David Robillard <http://drobilla.net>
+  Copyright (C) 2010 Leonard Ritter <paniq@paniq.org>
+ 
+  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
+*/
 
-/** @file
- * C header for the LV2 Persist extension <http://lv2plug.in/ns/ext/persist>.
- */
+/**
+   @file
+   C API for the LV2 Persist extension <http://lv2plug.in/ns/ext/persist>.
+*/
 
 #ifndef LV2_PERSIST_H
 #define LV2_PERSIST_H
@@ -29,32 +31,34 @@ extern "C" {
 
 #define LV2_PERSIST_URI "http://lv2plug.in/ns/ext/persist"
 
-/** A host-provided function to store a value under a given key.
- * @param callback_data Must be the callback_data passed to LV2_Persist.save().
- * @param key The URI key (predicate) under which the value is to be stored.
- * @param value Pointer to the value (object) to be stored.
- * @param size The size of the data at @a value in bytes.
- * @param type The type of @a value, as a URI mapped to an integer.
- *
- * The host passes a callback of this type to LV2_Persist.save().  This
- * callback is called repeatedly by the plugin within LV2_Persist.save() to
- * store all the key/value records that describe its current state.
- *
- * Unless @a type is 0, @a value is guaranteed to be POD (i.e. a region
- * of memory that does not contain pointers and can safely be copied
- * and persisted indefinitely with a simple memcpy).  If @a type is 0,
- * then @a value is a reference, as defined by the LV2 Atom extension
- * <http://lv2plug.in/ns/ext/atom/>.  Hosts are not required to support
- * references: a plugin MUST NOT expect a host to persist references unless
- * the host supports the feature <http://lv2plug.in/ns/ext/atom#blobSupport>.
- * Plugins SHOULD express their state entirely with POD values.
- *
- * Note that @a size MUST be > 0, and @a value MUST point to a valid region of
- * memory @a size bytes long (this is required to make restore unambiguous).
- *
- * The plugin MUST NOT attempt to use this function outside of the
- * LV2_Persist.restore() context.
- */
+/**
+   A host-provided function to store a value under a given key.
+   @param callback_data Must be the callback_data passed to LV2_Persist.save().
+   @param key The URI key (predicate) under which the value is to be stored.
+   @param value Pointer to the value (object) to be stored.
+   @param size The size of the data at @a value in bytes.
+   @param type The type of @a value, as a URI mapped to an integer.
+ 
+   The host passes a callback of this type to LV2_Persist.save().
+   This callback is called repeatedly by the plugin within
+   LV2_Persist.save() to store all the key/value records that describe
+   its current state.
+ 
+   Unless @a type is 0, @a value is guaranteed to be POD (i.e. a region
+   of memory that does not contain pointers and can safely be copied
+   and persisted indefinitely with a simple memcpy).  If @a type is 0,
+   then @a value is a reference, as defined by the LV2 Atom extension
+   <http://lv2plug.in/ns/ext/atom/>.  Hosts are not required to support
+   references: a plugin MUST NOT expect a host to persist references unless
+   the host supports the feature <http://lv2plug.in/ns/ext/atom#blobSupport>.
+   Plugins SHOULD express their state entirely with POD values.
+ 
+   Note that @a size MUST be > 0, and @a value MUST point to a valid region of
+   memory @a size bytes long (this is required to make restore unambiguous).
+ 
+   The plugin MUST NOT attempt to use this function outside of the
+   LV2_Persist.restore() context.
+*/
 typedef void (*LV2_Persist_Store_Function)(
 	void*       callback_data,
 	const char* key,
@@ -62,116 +66,122 @@ typedef void (*LV2_Persist_Store_Function)(
 	size_t      size,
 	uint32_t    type);
 
-/** A host-provided function to retrieve a value under a given key.
- * @param callback_data Must be the callback_data passed to LV2_Persist.restore().
- * @param key The URI key (predicate) under which a value has been stored.
- * @param size (Output) If non-NULL, set to the size of the restored value.
- * @param type (Output) If non-NULL, set to the type of the restored value.
- * @return A pointer to the restored value (object), or NULL if no value
- *         has been stored under @a key.
- *
- * A callback of this type is passed by the host to LV2_Persist.restore().  This
- * callback is called repeatedly by the plugin within LV2_Persist.restore() to
- * retrieve the values of any keys it requires to restore its state.
- *
- * The returned value MUST remain valid until LV2_Persist.restore() returns.
- *
- * The plugin MUST NOT attempt to use this function, or any value returned from
- * it, outside of the LV2_Persist.restore() context.  Returned values MAY be
- * copied for later use if necessary.
- */
+/**
+   A host-provided function to retrieve a value under a given key.
+   @param callback_data Must be the callback_data passed to LV2_Persist.restore().
+   @param key The URI key (predicate) under which a value has been stored.
+   @param size (Output) If non-NULL, set to the size of the restored value.
+   @param type (Output) If non-NULL, set to the type of the restored value.
+   @return A pointer to the restored value (object), or NULL if no value
+   has been stored under @a key.
+ 
+   A callback of this type is passed by the host to LV2_Persist.restore().  This
+   callback is called repeatedly by the plugin within LV2_Persist.restore() to
+   retrieve the values of any keys it requires to restore its state.
+ 
+   The returned value MUST remain valid until LV2_Persist.restore() returns.
+ 
+   The plugin MUST NOT attempt to use this function, or any value returned from
+   it, outside of the LV2_Persist.restore() context.  Returned values MAY be
+   copied for later use if necessary.
+*/
 typedef const void* (*LV2_Persist_Retrieve_Function)(
 	void*       callback_data,
 	const char* key,
 	size_t*     size,
 	uint32_t*   type);
 
-/** When the plugin's extension_data is called with argument LV2_PERSIST_URI,
- * the plugin MUST return an LV2_Persist structure, which remains valid for
- * the lifetime of the plugin.
- *
- * The host can use the contained function pointers to save and restore the
- * state of a plugin instance at any time (provided the threading restrictions
- * for the given function are met).
- *
- * The typical use case is to save the plugin's state when a project is
- * saved, and to restore the state when a project has been loaded.  Other
- * uses are possible (e.g. cloning plugin instances or taking a snapshot
- * of plugin state).
- *
- * Stored data is only guaranteed to be compatible between instances of plugins
- * with the same URI (i.e. if a change to a plugin would cause a fatal error
- * when restoring state saved by a previous version of that plugin, the plugin
- * URI must change just as it must when a plugin's ports change).  Plugin
- * authors should consider this possibility, and always store sensible data
- * with meaningful types to avoid such compatibility issues in the future.
- */
+/**
+   Persist Extension Data.
+
+   When the plugin's extension_data is called with argument LV2_PERSIST_URI,
+   the plugin MUST return an LV2_Persist structure, which remains valid for
+   the lifetime of the plugin.
+ 
+   The host can use the contained function pointers to save and restore the
+   state of a plugin instance at any time (provided the threading restrictions
+   for the given function are met).
+ 
+   The typical use case is to save the plugin's state when a project is
+   saved, and to restore the state when a project has been loaded.  Other
+   uses are possible (e.g. cloning plugin instances or taking a snapshot
+   of plugin state).
+ 
+   Stored data is only guaranteed to be compatible between instances of plugins
+   with the same URI (i.e. if a change to a plugin would cause a fatal error
+   when restoring state saved by a previous version of that plugin, the plugin
+   URI must change just as it must when a plugin's ports change).  Plugin
+   authors should consider this possibility, and always store sensible data
+   with meaningful types to avoid such compatibility issues in the future.
+*/
 typedef struct _LV2_Persist {
 	
-	/** Save plugin state using a host-provided @a store callback.
-	 *
-	 * @param instance The instance handle of the plugin.
-	 * @param store The host-provided store callback.
-	 * @param callback_data	An opaque pointer to host data, e.g. the map or
-	 *        file where the values are to be stored.  If @a store is called,
-	 *        this MUST be passed as its callback_data parameter.
-	 *
-	 * The plugin is expected to store everything necessary to completely
-	 * restore its state later (possibly much later, in a different
-	 * process, on a completely different machine, etc.)
-	 *
-	 * The @a callback_data pointer and @a store function MUST NOT be
-	 * used beyond the scope of save().
-	 *
-	 * This function has its own special threading class: it may not be
-	 * called concurrently with any "Instantiation" function, but it
-	 * may be called concurrently with functions in any other class,
-	 * unless the definition of that class prohibits it (e.g. it may
-	 * not be called concurrently with a "Discovery" function, but it
-	 * may be called concurrently with an "Audio" function.  The plugin
-	 * is responsible for any locking or lock-free techniques necessary
-	 * to make this possible.
-	 *
-	 * Note that in the simple case where state is only modified by
-	 * restore(), there are no synchronization issues since save() is
-	 * never called concurrently with restore() (though run() may read
-	 * it during a save).
-	 *
-	 * Plugins that dynamically modify state while running, however,
-	 * must take care to do so in such a way that a concurrent call to
-	 * save() will save a consistent representation of plugin state for a
-	 * single instant in time.  The simplest way to do this is to modify a
-	 * copy of the state map and atomically swap a pointer to the entire
-	 * map once the changes are complete (for very large state maps,
-	 * a purely functional map data structure may be more appropriate
-	 * since a complete copy is not necessary).
-	 */
+	/**
+	   Save plugin state using a host-provided @a store callback.
+	 
+	   @param instance The instance handle of the plugin.
+	   @param store The host-provided store callback.
+	   @param callback_data	An opaque pointer to host data, e.g. the map or
+	   file where the values are to be stored.  If @a store is called,
+	   this MUST be passed as its callback_data parameter.
+	 
+	   The plugin is expected to store everything necessary to completely
+	   restore its state later (possibly much later, in a different
+	   process, on a completely different machine, etc.)
+	 
+	   The @a callback_data pointer and @a store function MUST NOT be
+	   used beyond the scope of save().
+	 
+	   This function has its own special threading class: it may not be
+	   called concurrently with any "Instantiation" function, but it
+	   may be called concurrently with functions in any other class,
+	   unless the definition of that class prohibits it (e.g. it may
+	   not be called concurrently with a "Discovery" function, but it
+	   may be called concurrently with an "Audio" function.  The plugin
+	   is responsible for any locking or lock-free techniques necessary
+	   to make this possible.
+	 
+	   Note that in the simple case where state is only modified by
+	   restore(), there are no synchronization issues since save() is
+	   never called concurrently with restore() (though run() may read
+	   it during a save).
+	 
+	   Plugins that dynamically modify state while running, however,
+	   must take care to do so in such a way that a concurrent call to
+	   save() will save a consistent representation of plugin state for a
+	   single instant in time.  The simplest way to do this is to modify a
+	   copy of the state map and atomically swap a pointer to the entire
+	   map once the changes are complete (for very large state maps,
+	   a purely functional map data structure may be more appropriate
+	   since a complete copy is not necessary).
+	*/
 	void (*save)(LV2_Handle                 instance,
 	             LV2_Persist_Store_Function store,
 	             void*                      callback_data);
 
-	/** Restore plugin state using a host-provided @a retrieve callback.
-	 *
-	 * @param instance The instance handle of the plugin.
-	 * @param retrieve The host-provided retrieve callback.
-	 * @param callback_data	An opaque pointer to host data, e.g. the map or
-	 *        file from which the values are to be restored.  If @a retrieve is
-	 *        called, this MUST be passed as its callback_data parameter.
-	 *
-	 * The plugin MAY assume a restored value was set by a previous call to
-	 * LV2_Persist.save() by a plugin with the same URI.
-	 *
-	 * The plugin MUST gracefully fall back to a default value when a
-	 * value can not be retrieved.	This allows the host to reset the
-	 * plugin state with an empty map.
-	 *
-	 * The @a callback_data pointer and @a store function MUST NOT be used
-	 * beyond the scope of restore().
-	 *
-	 * This function is in the "Instantiation" threading class as defined
-	 * by LV2.  This means it MUST NOT be called concurrently with any other
-	 * function on the same plugin instance.
-	 */
+	/**
+	   Restore plugin state using a host-provided @a retrieve callback.
+	 
+	   @param instance The instance handle of the plugin.
+	   @param retrieve The host-provided retrieve callback.
+	   @param callback_data	An opaque pointer to host data, e.g. the map or
+	   file from which the values are to be restored.  If @a retrieve is
+	   called, this MUST be passed as its callback_data parameter.
+	 
+	   The plugin MAY assume a restored value was set by a previous call to
+	   LV2_Persist.save() by a plugin with the same URI.
+	 
+	   The plugin MUST gracefully fall back to a default value when a
+	   value can not be retrieved.	This allows the host to reset the
+	   plugin state with an empty map.
+	 
+	   The @a callback_data pointer and @a store function MUST NOT be used
+	   beyond the scope of restore().
+	 
+	   This function is in the "Instantiation" threading class as defined
+	   by LV2.  This means it MUST NOT be called concurrently with any other
+	   function on the same plugin instance.
+	*/
 	void (*restore)(LV2_Handle                    instance,
 	                LV2_Persist_Retrieve_Function retrieve,
 	                void*                         callback_data);