Tidy up documentation, remove cruft.

git-svn-id: http://svn.drobilla.net/lad/trunk/slv2@2924 a436a847-0d15-0410-975c-d299462d15a1

1 files changed, 24 insertions, 47 deletions

diff --git a/slv2/world.h b/slv2/world.h
index 8bd4b35..c360642 100644
--- a/slv2/world.h
+++ b/slv2/world.h
@@ -25,7 +25,7 @@ extern "C" {
 
 #include "slv2/collections.h"
 
-/** \defgroup slv2_world Global library state
+/** @defgroup slv2_world Global library state
  *
  * The "world" represents all library state, and the data found in bundles'
  * manifest.ttl (ie it is an in-memory index of all things LV2 found).
@@ -33,7 +33,7 @@ extern "C" {
  * extensions) itself can be queried from the world for use.
  *
  * Normal hosts which just want to easily load plugins by URI are strongly
- * recommended to simply call \ref slv2_world_load_all to find all installed
+ * recommended to simply call @ref slv2_world_load_all to find all installed
  * data in the recommended way.
  *
  * Normal hosts should NOT have to refer to bundles directly under normal
@@ -45,7 +45,6 @@ extern "C" {
  */
 
 /** Initialize a new, empty world.
- *
  * If initialization fails, NULL is returned.
  */
 SLV2_API
@@ -69,49 +68,38 @@ slv2_world_set_option(SLV2World       world,
                       const SLV2Value value);
 
 /** Destroy the world, mwahaha.
- *
- * NB: Destroying the world will leave dangling references in any plugin lists,
- * plugins, etc.  Do not destroy the world until you are finished with all
- * objects that came from it.
+ * Note that destroying @a world will destroy all the objects it contains
+ * (e.g. instances of SLV2Plugin).  Do not destroy the world until you are
+ * finished with all objects that came from it.
  */
 SLV2_API
 void
 slv2_world_free(SLV2World world);
 
 /** Load all installed LV2 bundles on the system.
- *
- * This is the recommended way for hosts to load LV2 data.  It does the most
- * reasonable thing to find all installed plugins, extensions, etc. on the
- * system.  The environment variable LV2_PATH may be used to set the
- * directories inside which this function will look for bundles.  Otherwise
- * a sensible, standard default will be used.
- *
- * Use of other functions for loading bundles is \em highly discouraged
- * without a special reason to do so - use this one.
- *
- * Time = Query
+ * This is the recommended way for hosts to load LV2 data.  It implements the
+ * established/standard best practice for discovering all LV2 data on the
+ * system.  The environment variable LV2_PATH may be used to control where
+ * this function will look for bundles.
+ *
+ * Hosts should use this function rather than explicitly load bundles, except
+ * in special circumstances (e.g. development utilities, or hosts that ship
+ * with special plugin bundles which are installed to a known location).
  */
 SLV2_API
 void
 slv2_world_load_all(SLV2World world);
 
 /** Load a specific bundle.
+ * @a bundle_uri must be a fully qualified URI to the bundle directory,
+ * with the trailing slash, eg. file:///usr/lib/lv2/foo.lv2/
  *
- * \arg bundle_uri A fully qualified URI to the bundle directory,
- * with the trailing slash, eg. file:///usr/lib/lv2/someBundle/
- *
- * Normal hosts should not use this function.
- *
- * Hosts should \b never attach any long-term significance to bundle paths
- * as there are no guarantees they will remain consistent whatsoever.
- * Plugins (and other things) are identified by URIs, \b not bundle or
- * file names.
- *
- * This function should only be used by apps which ship with a special
- * bundle (which it knows exists at some path because the bundle is
- * shipped with the application).
+ * Normal hosts should not need this function (use slv2_world_load_all).
  *
- * Time = Query
+ * Hosts MUST NOT attach any long-term significance to bundle paths
+ * (e.g. in save files), since there are no guarantees they will remain
+ * unchanged between (or even during) program invocations. Plugins (among
+ * other things) MUST be identified by URIs (not paths) in save files.
  */
 SLV2_API
 void
@@ -119,25 +107,19 @@ slv2_world_load_bundle(SLV2World world,
                        SLV2Value bundle_uri);
 
 /** Get the parent of all other plugin classes, lv2:Plugin.
- *
- * Time = O(1)
  */
 SLV2_API
 SLV2PluginClass
 slv2_world_get_plugin_class(SLV2World world);
 
 /** Return a list of all found plugin classes.
- *
  * Returned list is owned by world and must not be freed by the caller.
- *
- * Time = O(1)
  */
 SLV2_API
 SLV2PluginClasses
 slv2_world_get_plugin_classes(SLV2World world);
 
 /** Return a list of all found plugins.
- *
  * The returned list contains just enough references to query
  * or instantiate plugins.  The data for a particular plugin will not be
  * loaded into memory until a call to an slv2_plugin_* function results in
@@ -145,24 +127,19 @@ slv2_world_get_plugin_classes(SLV2World world);
  * queries are very fast).
  *
  * Returned list must be freed by user with slv2_plugins_free.  The contained
- * plugins are owned by \a world and must not be freed by caller.
- *
- * Time = O(1)
+ * plugins are owned by @a world and must not be freed by caller.
  */
 SLV2_API
 SLV2Plugins
 slv2_world_get_all_plugins(SLV2World world);
 
 /** Return a list of found plugins filtered by a user-defined filter function.
- *
- * All plugins currently found in \a world that return true when passed to
- * \a include (a pointer to a function which takes an SLV2Plugin and returns
+ * All plugins currently found in @a world that return true when passed to
+ * @a include (a pointer to a function which takes an SLV2Plugin and returns
  * a bool) will be in the returned list.
  *
  * Returned list must be freed by user with slv2_plugins_free.  The contained
- * plugins are owned by \a world and must not be freed by caller.
- *
- * Time = O(n * Time(include))
+ * plugins are owned by @a world and must not be freed by caller.
  */
 SLV2_API
 SLV2Plugins