Add methods documentation page.

Clean up OSC documentation pages.


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

8 files changed, 224 insertions, 151 deletions

diff --git a/src/engine/ClientBroadcaster.cpp b/src/engine/ClientBroadcaster.cpp
index beb08f22..c0f107de 100644
--- a/src/engine/ClientBroadcaster.cpp
+++ b/src/engine/ClientBroadcaster.cpp
@@ -132,7 +132,7 @@ ClientBroadcaster::send_plugins(const NodeFactory::Plugins& plugins)
 
 
 void
-ClientBroadcaster::send_destroyed(const Path& path)
+ClientBroadcaster::send_deleted(const Path& path)
 {
 	for (Clients::const_iterator i = _clients.begin(); i != _clients.end(); ++i)
 		(*i).second->del(path);
@@ -210,6 +210,7 @@ ClientBroadcaster::send_activity(const Path& path)
 
 /** Send an object.
  *
+ * @param p         Object to send
  * @param recursive If true send all children of object
  */
 void
diff --git a/src/engine/ClientBroadcaster.hpp b/src/engine/ClientBroadcaster.hpp
index a207b6d7..2aea8eb0 100644
--- a/src/engine/ClientBroadcaster.hpp
+++ b/src/engine/ClientBroadcaster.hpp
@@ -64,7 +64,7 @@ public:
 
 	void send_plugins(const NodeFactory::Plugins& plugin_list);
 	void send_object(const GraphObjectImpl* p, bool recursive);
-	void send_destroyed(const Raul::Path& path);
+	void send_deleted(const Raul::Path& path);
 	void send_clear_patch(const Raul::Path& patch_path);
 	void send_connection(const SharedPtr<const ConnectionImpl> connection);
 	void send_disconnection(const Raul::Path& src_port_path, const Raul::Path& dst_port_path);
diff --git a/src/engine/Event.cpp b/src/engine/Event.cpp
index ec21afde..e48d32a2 100644
--- a/src/engine/Event.cpp
+++ b/src/engine/Event.cpp
@@ -19,6 +19,13 @@
 #include "ThreadManager.hpp"
 #include "ProcessContext.hpp"
 
+/*! \page methods Method Documentation
+ *
+ * <p>All changes in Ingen (both engine and client) occur as a result of
+ * a small set of methods defined in terms of RDF and matching the
+ * HTTP and WebDAV standards as closely as possible.</p>
+ */
+
 namespace Ingen {
 
 
diff --git a/src/engine/OSCClientSender.cpp b/src/engine/OSCClientSender.cpp
index c0a6b85b..594266aa 100644
--- a/src/engine/OSCClientSender.cpp
+++ b/src/engine/OSCClientSender.cpp
@@ -36,38 +36,16 @@ namespace Ingen {
 
 /*! \page client_osc_namespace Client OSC Namespace Documentation
  *
- * <p>NOTE: this comment doesn't really apply any longer.. sort of.
- * but maybe it still should.. maybe.  so it remains...</p>
- *
- * <p>These are all the messages sent from the engine to the client.
- * Communication takes place over two distinct bands: control band and
- * notification band.</p>
- * <p>The control band is where clients send commands, and receive a simple
- * response, either OK or an error.</p>
- * <p>All notifications of engine state (ie new nodes) are sent over the
- * notification band <em>which is seperate from the control band</em>.  The
- * reasoning behind this is that many clients may be connected at the same
- * time - a client may receive notifications that are not a direct consequence
- * of some message it sent.</p>
- * <p>The notification band can be thought of as a stream of events representing
- * the changing engine state.  For example, It is possible for a client to send
- * commands and receive aknowledgements, and not listen to the notification band
- * at all; or (in the near future anyway) for a client to use UDP for the control
- * band (for speed), and TCP for the notification band (for reliability and
- * order guarantees).</p>
- * \n\n
+ * <p>These are the commands the client recognizes.  All monitoring of
+ * changes in the engine happens via these commands.</p>
  */
 
 
 /** \page client_osc_namespace
- * \n
- * <h2>Control Band</h2>
- */
-
-/** \page client_osc_namespace
- * <p> \b /ingen/ok - Respond to a successful user command
+ * <h2>/ingen/ok</h2>
  * \arg \b response-id (int) - Request ID this is a response to
- * </p> \n \n
+ *
+ * Successful response to some command.
  */
 void
 OSCClientSender::response_ok(int32_t id)
@@ -83,10 +61,11 @@ OSCClientSender::response_ok(int32_t id)
 
 
 /** \page client_osc_namespace
- * <p> \b /ingen/response - Respond to a user command
+ * <h2>/ingen/error</h2>
  * \arg \b response-id (int) - Request ID this is a response to
  * \arg \b message (string) - Error message (natural language text)
- * </p> \n \n
+ *
+ * Unsuccessful response to some command.
  */
 void
 OSCClientSender::response_error(int32_t id, const std::string& msg)
@@ -102,16 +81,12 @@ OSCClientSender::response_error(int32_t id, const std::string& msg)
 
 
 /** \page client_osc_namespace
- * \n
- * <h2>Notification Band</h2>
- */
-
-
-/** \page client_osc_namespace
- * <p> \b /ingen/error - Notification that an error has occurred
- * \arg \b message (string) - Error message (natural language text) \n\n
- * \li This is for notification of errors that aren't a direct response to a
- * user command, ie "unexpected" errors.</p> \n \n
+ * <h2>/ingen/error</h2>
+ * \arg \b message (string) - Error message (natural language text)
+ *
+ * Notification that an error has occurred.
+ * This is for notification of errors that aren't a direct response to a
+ * user command, ie "unexpected" errors.
  */
 void
 OSCClientSender::error(const std::string& msg)
@@ -120,6 +95,15 @@ OSCClientSender::error(const std::string& msg)
 }
 
 
+/** \page client_osc_namespace
+ * <h2>/ingen/put</h2>
+ * \arg \b path (string) - Path of object
+ * \arg \b predicate
+ * \arg \b value
+ * \arg \b ...
+ *
+ * PUT a set of properties to a path (see \ref methods).
+ */
 void
 OSCClientSender::put(const Raul::Path&                   path,
                      const Shared::Resource::Properties& properties)
@@ -129,19 +113,39 @@ OSCClientSender::put(const Raul::Path&                   path,
 
 
 /** \page client_osc_namespace
- * <p> \b /ingen/destroyed - Notification an object has been destroyed
- * \arg \b path (string) - Path of object (which no longer exists) </p> \n \n
+ * <h2>/ingen/move</h2>
+ * \arg \b old-path (string) - Old path of object
+ * \arg \b new-path (string) - New path of object
+ *
+ * MOVE an object to a new path (see \ref methods).
+ * The new path will have the same parent as the old path.
+ */
+void
+OSCClientSender::move(const Path& old_path, const Path& new_path)
+{
+	send("/ingen/move", "ss", old_path.c_str(), new_path.c_str(), LO_ARGS_END);
+}
+
+
+
+/** \page client_osc_namespace
+ * <h2>/ingen/delete</h2>
+ * \arg \b path (string) - Path of object (which no longer exists)
+ *
+ * DELETE an object (see \ref methods).
  */
 void
 OSCClientSender::del(const Path& path)
 {
-	send("/ingen/destroyed", "s", path.c_str(), LO_ARGS_END);
+	send("/ingen/delete", "s", path.c_str(), LO_ARGS_END);
 }
 
 
 /** \page client_osc_namespace
- * <p> \b /ingen/clear_patch - Notification a patch has been cleared (all children destroyed)
- * \arg \b path (string) - Path of patch (which is now empty)</p> \n \n
+ * <h2>/ingen/clear_patch</h2>
+ * \arg \b path (string) - Path of patch (which is now empty)
+ *
+ * Notification a patch has been cleared (all children deleted).
  */
 void
 OSCClientSender::clear_patch(const Path& patch_path)
@@ -151,9 +155,11 @@ OSCClientSender::clear_patch(const Path& patch_path)
 
 
 /** \page client_osc_namespace
- * <p> \b /ingen/new_connection - Notification a new connection has been made.
+ * <h2>/ingen/new_connection</h2>
  * \arg \b src-path (string) - Path of the source port
- * \arg \b dst-path (string) - Path of the destination port</p> \n \n
+ * \arg \b dst-path (string) - Path of the destination port
+ *
+ * Notification a new connection has been made.
  */
 void
 OSCClientSender::connect(const Path& src_port_path, const Path& dst_port_path)
@@ -163,9 +169,11 @@ OSCClientSender::connect(const Path& src_port_path, const Path& dst_port_path)
 
 
 /** \page client_osc_namespace
- * <p> \b /ingen/disconnection - Notification a connection has been unmade.
+ * <h2>/ingen/disconnection</h2>
  * \arg \b src-path (string) - Path of the source port
- * \arg \b dst-path (string) - Path of the destination port</p> \n \n
+ * \arg \b dst-path (string) - Path of the destination port
+ *
+ * Notification a connection has been unmade.
  */
 void
 OSCClientSender::disconnect(const Path& src_port_path, const Path& dst_port_path)
@@ -175,10 +183,12 @@ OSCClientSender::disconnect(const Path& src_port_path, const Path& dst_port_path
 
 
 /** \page client_osc_namespace
- * <p> \b /ingen/set_variable - Notification of a variable.
+ * <h2>/ingen/set_variable</h2>
  * \arg \b path (string) - Path of the object associated with variable (node, patch, or port)
  * \arg \b key (string)
- * \arg \b value (string)</p> \n \n
+ * \arg \b value (string)
+ * ,
+ * Notification of a variable.
  */
 void
 OSCClientSender::set_variable(const URI& path, const URI& key, const Atom& value)
@@ -192,10 +202,12 @@ OSCClientSender::set_variable(const URI& path, const URI& key, const Atom& value
 
 
 /** \page client_osc_namespace
- * <p> \b /ingen/set_property - Notification of a property.
+ * <h2>/ingen/set_property</h2>
  * \arg \b path (string) - Path of the object associated with property (node, patch, or port)
  * \arg \b key (string)
- * \arg \b value (string)</p> \n \n
+ * \arg \b value (string)
+ *
+ * Notification of a property.
  */
 void
 OSCClientSender::set_property(const URI& path, const URI& key, const Atom& value)
@@ -209,9 +221,11 @@ OSCClientSender::set_property(const URI& path, const URI& key, const Atom& value
 
 
 /** \page client_osc_namespace
- * <p> \b /ingen/set_port_value - Notification the value of a port has changed
+ * <h2>/ingen/set_port_value</h2>
  * \arg \b path (string) - Path of port
- * \arg \b value (any) - New value of port </p> \n \n
+ * \arg \b value (any) - New value of port
+ *
+ * Notification the value of a port has changed.
  */
 void
 OSCClientSender::set_port_value(const Path& port_path, const Atom& value)
@@ -224,10 +238,12 @@ OSCClientSender::set_port_value(const Path& port_path, const Atom& value)
 
 
 /** \page client_osc_namespace
- * <p> \b /ingen/set_port_value - Notification the value of a port has changed
+ * <h2>/ingen/set_port_value</h2>
  * \arg \b path (string) - Path of port
  * \arg \b voice (int) - Voice which is set to this value
- * \arg \b value (any) - New value of port </p> \n \n
+ * \arg \b value (any) - New value of port
+ *
+ * Notification the value of a port has changed.
  */
 void
 OSCClientSender::set_voice_value(const Path& port_path, uint32_t voice, const Atom& value)
@@ -240,8 +256,10 @@ OSCClientSender::set_voice_value(const Path& port_path, uint32_t voice, const At
 
 
 /** \page client_osc_namespace
- * <p> \b /ingen/activity - Notification of "activity" (e.g. port message blinkenlights)
- * \arg \b path (string) - Path of object </p> \n \n
+ * <h2>/ingen/activity</h2>
+ * \arg \b path (string) - Path of object
+ *
+ * Notification of "activity" (e.g. port message blinkenlights).
  */
 void
 OSCClientSender::activity(const Path& path)
@@ -254,11 +272,13 @@ OSCClientSender::activity(const Path& path)
 
 
 /** \page client_osc_namespace
- * <p> \b /ingen/plugin - Notification of the existance of a plugin
+ * <h2>/ingen/plugin</h2>
  * \arg \b uri (string) - URI of plugin (e.g. http://example.org/filtermatic)
  * \arg \b type (string) - Type of plugin (e.g. "lv2:Plugin", "ingen:LADSPAPlugin")
  * \arg \b symbol (string) - Valid symbol for plugin (default symbol for nodes) (e.g. "adsr")
  * \arg \b name (string) - Descriptive human-readable name of plugin (e.g. "ADSR Envelope")
+ *
+ * Notification of the existence of a plugin.
  */
 void
 OSCClientSender::new_plugin(const URI&    uri,
@@ -273,16 +293,4 @@ OSCClientSender::new_plugin(const URI&    uri,
 }
 
 
-/** \page client_osc_namespace
- * <p> \b /ingen/move - Notification of an object's renaming
- * \arg \b old-path (string) - Old path of object
- * \arg \b new-path (string) - New path of object </p> \n \n
- */
-void
-OSCClientSender::move(const Path& old_path, const Path& new_path)
-{
-	send("/ingen/move", "ss", old_path.c_str(), new_path.c_str(), LO_ARGS_END);
-}
-
-
 } // namespace Ingen
diff --git a/src/engine/OSCEngineReceiver.cpp b/src/engine/OSCEngineReceiver.cpp
index 28509ad7..a5f01c74 100644
--- a/src/engine/OSCEngineReceiver.cpp
+++ b/src/engine/OSCEngineReceiver.cpp
@@ -44,7 +44,7 @@ namespace Ingen {
  *
  * <p>All commands on this page are in the "control band".  If a client needs to
  * know about the state of the engine, it must listen to the "notification band".
- * See the "Client OSC Namespace Documentation" for details.</p>\n\n
+ * See the "Client OSC Namespace Documentation" for details.
  */
 
 
@@ -243,8 +243,10 @@ OSCEngineReceiver::error_cb(int num, const char* msg, const char* path)
 
 
 /** \page engine_osc_namespace
- * <p> \b /ingen/ping - Immediately sends a successful response to the given response id.
- * \arg \b response-id (integer) </p> \n \n
+ * <h2>/ingen/ping</h2>
+ * \arg \b response-id (integer)
+ *
+ * Reply to sender immediately with a successful response.
  */
 int
 OSCEngineReceiver::_ping_cb(const char* path, const char* types, lo_arg** argv, int argc, lo_message msg)
@@ -257,13 +259,13 @@ OSCEngineReceiver::_ping_cb(const char* path, const char* types, lo_arg** argv,
 
 
 /** \page engine_osc_namespace
- * <p> \b /ingen/ping_queued - Sends response after going through the event queue.
+ * <h2>/ingen/ping_queued</h2>
  * \arg \b response-id (integer)
  *
- * \li See the documentation for /ingen/set_port_value_queued for an explanation of how
- * this differs from /ingen/ping.  This is useful to send after sending a large cluster of
- * events as a sentinel and wait on it's response, to know when the events are all
- * finished processing.</p> \n \n
+ * Reply to sender with a successful response after going through the event queue.
+ * This is useful for checking if the engine is actually active, or for sending after
+ * several events as a sentinel and wait on it's response, to know when all previous
+ * events have finished processing.
  */
 int
 OSCEngineReceiver::_ping_slow_cb(const char* path, const char* types, lo_arg** argv, int argc, lo_message msg)
@@ -274,12 +276,13 @@ OSCEngineReceiver::_ping_slow_cb(const char* path, const char* types, lo_arg** a
 
 
 /** \page engine_osc_namespace
- * <p> \b /ingen/quit - Terminates the engine.
+ * <h2>/ingen/quit</h2>
  * \arg \b response-id (integer)
  *
- * \li Note that there is NO order guarantees with this command at all.  You could
+ * Terminate the engine.
+ * Note that there are NO order guarantees with this command at all.  You could
  * send 10 messages then quit, and the quit reply could come immediately and the
- * 10 messages would never get executed. </p> \n \n
+ * 10 messages would never get executed.
  */
 int
 OSCEngineReceiver::_quit_cb(const char* path, const char* types, lo_arg** argv, int argc, lo_message msg)
@@ -288,11 +291,14 @@ OSCEngineReceiver::_quit_cb(const char* path, const char* types, lo_arg** argv,
 	return 0;
 }
 
+
 /** \page engine_osc_namespace
- * <p> \b /ingen/register_client - Registers a new client with the engine
- * \arg \b response-id (integer) \n\n
- * \li The incoming address will be used for the new registered client.  If you
- * want to register a different specific address, use the URL version. </p> \n \n
+ * <h2>/ingen/register_client</h2>
+ * \arg \b response-id (integer)
+ *
+ * Register a new client with the engine.
+ * The incoming address will be used for the new registered client.  If you
+ * want to register a different specific address, use the URL version.
  */
 int
 OSCEngineReceiver::_register_client_cb(const char* path, const char* types, lo_arg** argv, int argc, lo_message msg)
@@ -309,8 +315,10 @@ OSCEngineReceiver::_register_client_cb(const char* path, const char* types, lo_a
 
 
 /** \page engine_osc_namespace
- * <p> \b /ingen/unregister_client - Unregisters a client
- * \arg \b response-id (integer) </p> \n \n
+ * <h2>/ingen/unregister_client</h2>
+ * \arg \b response-id (integer)
+ *
+ * Unregister a client.
  */
 int
 OSCEngineReceiver::_unregister_client_cb(const char* path, const char* types, lo_arg** argv, int argc, lo_message msg)
@@ -326,8 +334,10 @@ OSCEngineReceiver::_unregister_client_cb(const char* path, const char* types, lo
 
 
 /** \page engine_osc_namespace
- * <p> \b /ingen/load_plugins - Locates all available plugins, making them available for use.
- * \arg \b response-id (integer) </p> \n \n
+ * <h2>/ingen/load_plugins</h2>
+ * \arg \b response-id (integer)
+ *
+ * Locate all available plugins, making them available for use.
  */
 int
 OSCEngineReceiver::_load_plugins_cb(const char* path, const char* types, lo_arg** argv, int argc, lo_message msg)
@@ -338,11 +348,12 @@ OSCEngineReceiver::_load_plugins_cb(const char* path, const char* types, lo_arg*
 
 
 /** \page engine_osc_namespace
- * <p> \b /ingen/activate - Activate the engine (MIDI, audio, everything)
- * \arg \b response-id (integer) </p>
+ * <h2>/ingen/activate</h2>
+ * \arg \b response-id (integer)
  *
- * \li Note that you <b>must</b> send this message first if you want the engine to do
- * anything at all - <em>including respond to your messages!</em> \n \n
+ * Activate the engine (event processing and all drivers, e.g. audio and MIDI).
+ * Note that you <b>must</b> send this message first if you want the engine to do
+ * anything at all - <em>including respond to your messages!</em>
  */
 int
 OSCEngineReceiver::_engine_activate_cb(const char* path, const char* types, lo_arg** argv, int argc, lo_message msg)
@@ -353,8 +364,10 @@ OSCEngineReceiver::_engine_activate_cb(const char* path, const char* types, lo_a
 
 
 /** \page engine_osc_namespace
- * <p> \b /ingen/deactivate - Deactivate the engine completely.
- * \arg \b response-id (integer) </p> \n \n
+ * <h2>/ingen/deactivate</h2>
+ * \arg \b response-id (integer)
+ *
+ * Deactivate the engine.
  */
 int
 OSCEngineReceiver::_engine_deactivate_cb(const char* path, const char* types, lo_arg** argv, int argc, lo_message msg)
@@ -365,10 +378,12 @@ OSCEngineReceiver::_engine_deactivate_cb(const char* path, const char* types, lo
 
 
 /** \page engine_osc_namespace
- * <p> \b /ingen/move - Move (rename) an Object
+ * <h2>/ingen/move</h2>
  * \arg \b response-id (integer)
  * \arg \b old-path - Object's path
- * \arg \b new-path - Object's new path </p> \n \n
+ * \arg \b new-path - Object's new path
+ *
+ * Move (rename) an Object.
  */
 int
 OSCEngineReceiver::_move_cb(const char* path, const char* types, lo_arg** argv, int argc, lo_message msg)
@@ -382,9 +397,11 @@ OSCEngineReceiver::_move_cb(const char* path, const char* types, lo_arg** argv,
 
 
 /** \page engine_osc_namespace
- * <p> \b /ingen/clear_patch - Remove all nodes from a patch
+ * <h2>/ingen/clear_patch</h2>
  * \arg \b response-id (integer)
- * \arg \b patch-path - Patch's path </p> \n \n
+ * \arg \b patch-path - Patch's path
+ *
+ * Remove all nodes from a patch.
  */
 int
 OSCEngineReceiver::_clear_patch_cb(const char* path, const char* types, lo_arg** argv, int argc, lo_message msg)
@@ -397,9 +414,11 @@ OSCEngineReceiver::_clear_patch_cb(const char* path, const char* types, lo_arg**
 
 
 /** \page engine_osc_namespace
- * <p> \b /ingen/del - Delete a graph object
+ * <h2>/ingen/del</h2>
  * \arg \b response-id (integer)
- * \arg \b path (string) - Full path of the object </p> \n \n
+ * \arg \b path (string) - Full path of the object
+ *
+ * Delete a graph object.
  */
 int
 OSCEngineReceiver::_del_cb(const char* path, const char* types, lo_arg** argv, int argc, lo_message msg)
@@ -412,10 +431,12 @@ OSCEngineReceiver::_del_cb(const char* path, const char* types, lo_arg** argv, i
 
 
 /** \page engine_osc_namespace
- * <p> \b /ingen/connect - Connects two ports (must be in the same patch)
+ * <h2>/ingen/connect</h2>
  * \arg \b response-id (integer)
  * \arg \b src-port-path (string) - Full path of source port
- * \arg \b dst-port-path (string) - Full path of destination port </p> \n \n
+ * \arg \b dst-port-path (string) - Full path of destination port
+ *
+ * Connect two ports (which must be in the same patch).
  */
 int
 OSCEngineReceiver::_connect_cb(const char* path, const char* types, lo_arg** argv, int argc, lo_message msg)
@@ -429,10 +450,12 @@ OSCEngineReceiver::_connect_cb(const char* path, const char* types, lo_arg** arg
 
 
 /** \page engine_osc_namespace
- * <p> \b /ingen/disconnect - Disconnects two ports.
+ * <h2>/ingen/disconnect</h2>
  * \arg \b response-id (integer)
  * \arg \b src-port-path (string) - Full path of source port
- * \arg \b dst-port-path (string) - Full path of destination port </p> \n \n
+ * \arg \b dst-port-path (string) - Full path of destination port
+ *
+ * Disconnect two ports.
  */
 int
 OSCEngineReceiver::_disconnect_cb(const char* path, const char* types, lo_arg** argv, int argc, lo_message msg)
@@ -446,10 +469,12 @@ OSCEngineReceiver::_disconnect_cb(const char* path, const char* types, lo_arg**
 
 
 /** \page engine_osc_namespace
- * <p> \b /ingen/disconnect_all - Disconnect all connections to/from a node/port.
+ * <h2>/ingen/disconnect_all</h2>
  * \arg \b response-id (integer)
- * \arg \b patch-path (string) - The (parent) patch in which to disconnect object. </p> \n \n
- * \arg \b object-path (string) - Full path of object. </p> \n \n
+ * \arg \b patch-path (string) - The (parent) patch in which to disconnect object.
+ * \arg \b object-path (string) - Full path of object.
+ *
+ * Disconnect all connections to/from a node/port.
  */
 int
 OSCEngineReceiver::_disconnect_all_cb(const char* path, const char* types, lo_arg** argv, int argc, lo_message msg)
@@ -463,10 +488,12 @@ OSCEngineReceiver::_disconnect_all_cb(const char* path, const char* types, lo_ar
 
 
 /** \page engine_osc_namespace
- * <p> \b /ingen/set_port_value - Sets the value of a port for all voices (as a QueuedEvent)
+ * <h2>/ingen/set_port_value</h2>
  * \arg \b response-id (integer)
  * \arg \b port-path (string) - Name of port
- * \arg \b value (float) - Value to set port to.</p> \n \n
+ * \arg \b value (float) - Value to set port to.
+ *
+ * Set the value of a port for all voices.
  */
 int
 OSCEngineReceiver::_set_port_value_cb(const char* path, const char* types, lo_arg** argv, int argc, lo_message msg)
@@ -511,11 +538,13 @@ OSCEngineReceiver::_set_port_value_cb(const char* path, const char* types, lo_ar
 
 
 /** \page engine_osc_namespace
- * <p> \b /ingen/note_on - Triggers a note-on, just as if it came from MIDI
+ * <h2>/ingen/note_on</h2>
  * \arg \b response-id (integer)
  * \arg \b node-path (string) - Patch of Node to trigger (must be a trigger or note node)
  * \arg \b note-num (int) - MIDI style note number (0-127)
- * \arg \b velocity (int) - MIDI style velocity (0-127)</p> \n \n
+ * \arg \b velocity (int) - MIDI style velocity (0-127)
+ *
+ * Trigger a note-on, just as if it came from MIDI.
  */
 int
 OSCEngineReceiver::_note_on_cb(const char* path, const char* types, lo_arg** argv, int argc, lo_message msg)
@@ -532,10 +561,12 @@ OSCEngineReceiver::_note_on_cb(const char* path, const char* types, lo_arg** arg
 
 
 /** \page engine_osc_namespace
- * <p> \b /ingen/note_off - Triggers a note-off, just as if it came from MIDI
+ * <h2>/ingen/note_off</h2>
  * \arg \b response-id (integer)
  * \arg \b node-path (string) - Patch of Node to trigger (must be a trigger or note node)
- * \arg \b note-num (int) - MIDI style note number (0-127)</p> \n \n
+ * \arg \b note-num (int) - MIDI style note number (0-127)
+ *
+ * Trigger a note-off, just as if it came from MIDI.
  */
 int
 OSCEngineReceiver::_note_off_cb(const char* path, const char* types, lo_arg** argv, int argc, lo_message msg)
@@ -551,9 +582,11 @@ OSCEngineReceiver::_note_off_cb(const char* path, const char* types, lo_arg** ar
 
 
 /** \page engine_osc_namespace
- * <p> \b /ingen/all_notes_off - Triggers a note-off for all voices, just as if it came from MIDI
+ * <h2>/ingen/all_notes_off</h2>
  * \arg \b response-id (integer)
- * \arg \b patch-path (string) - Patch of patch to send event to </p> \n \n
+ * \arg \b patch-path (string) - Patch of patch to send event to
+ *
+ * Trigger a note-off for all voices, just as if it came from MIDI.
  */
 int
 OSCEngineReceiver::_all_notes_off_cb(const char* path, const char* types, lo_arg** argv, int argc, lo_message msg)
@@ -569,14 +602,14 @@ OSCEngineReceiver::_all_notes_off_cb(const char* path, const char* types, lo_arg
 
 
 /** \page engine_osc_namespace
- * <p> \b /ingen/midi_learn - Initiate MIDI learn for a given (MIDI Control) Node
+ * <h2>/ingen/midi_learn</h2>
  * \arg \b response-id (integer)
- * \arg \b node-path (string) - Patch of the Node that should learn the next MIDI event.
+ * \arg \b node-path (string) - Path of control node.
  *
- * \li This of course will only do anything for MIDI control nodes.  The node will learn the next MIDI
- * event that arrives at it's MIDI input port - no behind the scenes voodoo happens here.  It is planned
- * that a plugin specification supporting arbitrary OSC commands for plugins will exist one day, and this
- * method will go away completely. </p> \n \n
+ * Initiate MIDI learn for a given control node.
+ * The node will learn the next MIDI control event it receives and set
+ * its outputs accordingly.
+ * This command does nothing for objects that are not a control internal.
  */
 int
 OSCEngineReceiver::_midi_learn_cb(const char* path, const char* types, lo_arg** argv, int argc, lo_message msg)
@@ -589,11 +622,13 @@ OSCEngineReceiver::_midi_learn_cb(const char* path, const char* types, lo_arg**
 
 
 /** \page engine_osc_namespace
- * <p> \b /ingen/set_variable - Set a variable, associated with a synth-space object (node, etc)
+ * <h2>/ingen/set_variable</h2>
  * \arg \b response-id (integer)
  * \arg \b object-path (string) - Full path of object to associate variable with
  * \arg \b key (string) - Key (index/predicate/ID) for new variable
- * \arg \b value (string) - Value of new variable </p> \n \n
+ * \arg \b value (string) - Value of new variable
+ *
+ * Set a variable, associated with a graph object.
  */
 int
 OSCEngineReceiver::_variable_set_cb(const char* path, const char* types, lo_arg** argv, int argc, lo_message msg)
@@ -612,11 +647,13 @@ OSCEngineReceiver::_variable_set_cb(const char* path, const char* types, lo_arg*
 
 
 /** \page engine_osc_namespace
- * <p> \b /ingen/set_property - Set an (RDF) property, associated with a synth-space object (node, etc)
+ * <h2>/ingen/set_property</h2>
  * \arg \b response-id (integer)
  * \arg \b object-path (string) - Full path of object to associate variable with
  * \arg \b key (string) - URI/QName for predicate of this property (e.g. "ingen:enabled")
- * \arg \b value (string) - Value of property </p> \n \n
+ * \arg \b value (string) - Value of property
+ *
+ * Set a property on a graph object.
  */
 int
 OSCEngineReceiver::_property_set_cb(const char* path, const char* types, lo_arg** argv, int argc, lo_message msg)
@@ -635,12 +672,12 @@ OSCEngineReceiver::_property_set_cb(const char* path, const char* types, lo_arg*
 
 
 /** \page engine_osc_namespace
- * <p> \b /ingen/request_variable - Requests the engine send a piece of variable, associated with a synth-space object (node, etc)
+ * <h2>/ingen/request_variable</h2>
  * \arg \b response-id (integer)
  * \arg \b object-path (string) - Full path of object variable is associated with
  * \arg \b key (string) - Key (index) for piece of variable
  *
- * \li Reply will be sent to client registered with the source address of this message.</p> \n \n
+ * Request the value of a variable on a graph object.
  */
 int
 OSCEngineReceiver::_variable_get_cb(const char* path, const char* types, lo_arg** argv, int argc, lo_message msg)
@@ -654,10 +691,11 @@ OSCEngineReceiver::_variable_get_cb(const char* path, const char* types, lo_arg*
 
 
 /** \page engine_osc_namespace
- * <p> \b /ingen/request_plugin - Requests the engine send the value of a port.
+ * <h2>/ingen/request_plugin</h2>
  * \arg \b response-id (integer)
- * \arg \b port-path (string) - Full path of port to send the value of \n\n
- * \li Reply will be sent to client registered with the source address of this message.</p>\n\n
+ * \arg \b port-path (string) - Full path of port to send the value of
+ *
+ * Request the value of a port.
  */
 int
 OSCEngineReceiver::_request_plugin_cb(const char* path, const char* types, lo_arg** argv, int argc, lo_message msg)
@@ -670,10 +708,11 @@ OSCEngineReceiver::_request_plugin_cb(const char* path, const char* types, lo_ar
 
 
 /** \page engine_osc_namespace
- * <p> \b /ingen/request_object - Requests the engine send the value of a port.
+ * <h2>/ingen/request_object</h2>
  * \arg \b response-id (integer)
  * \arg \b port-path (string) - Full path of port to send the value of \n\n
- * \li Reply will be sent to client registered with the source address of this message.</p>\n\n
+ *
+ * Request all properties of a graph object.
  */
 int
 OSCEngineReceiver::_request_object_cb(const char* path, const char* types, lo_arg** argv, int argc, lo_message msg)
@@ -686,9 +725,10 @@ OSCEngineReceiver::_request_object_cb(const char* path, const char* types, lo_ar
 
 
 /** \page engine_osc_namespace
- * <p> \b /ingen/request_plugins - Requests the engine send a list of all known plugins.
- * \arg \b response-id (integer) \n\n
- * \li Reply will be sent to client registered with the source address of this message.</p>\n\n
+ * <h2>/ingen/request_plugins</h2>
+ * \arg \b response-id (integer)
+ *
+ * Request the engine send a list of all known plugins.
  */
 int
 OSCEngineReceiver::_request_plugins_cb(const char* path, const char* types, lo_arg** argv, int argc, lo_message msg)
@@ -699,9 +739,10 @@ OSCEngineReceiver::_request_plugins_cb(const char* path, const char* types, lo_a
 
 
 /** \page engine_osc_namespace
- * <p> \b /ingen/request_all_objects - Requests the engine send information about \em all objects (patches, nodes, etc)
- * \arg \b response-id (integer)\n\n
- * \li Reply will be sent to client registered with the source address of this message.</p> \n \n
+ * <h2>/ingen/request_all_objects</h2>
+ * \arg \b response-id (integer)
+ *
+ * Requests all information about all known objects.
  */
 int
 OSCEngineReceiver::_request_all_objects_cb(const char* path, const char* types, lo_arg** argv, int argc, lo_message msg)
diff --git a/src/engine/events/DeleteEvent.cpp b/src/engine/events/DeleteEvent.cpp
index 21058546..958a8d42 100644
--- a/src/engine/events/DeleteEvent.cpp
+++ b/src/engine/events/DeleteEvent.cpp
@@ -88,7 +88,7 @@ DeleteEvent::pre_process()
 				// FIXME: is this called multiple times?
 				_compiled_patch = _node->parent_patch()->compile();
 #ifndef NDEBUG
-				// Be sure node is removed from process order, so it can be destroyed
+				// Be sure node is removed from process order, so it can be deleted
 				for (size_t i=0; i < _compiled_patch->size(); ++i) {
 					assert(_compiled_patch->at(i).node() != _node.get());
 					// FIXME: check providers/dependants too
@@ -187,7 +187,7 @@ DeleteEvent::post_process()
 		_engine.broadcaster()->bundle_begin();
 		if (_disconnect_event)
 			_disconnect_event->post_process();
-		_engine.broadcaster()->send_destroyed(_path);
+		_engine.broadcaster()->send_deleted(_path);
 		_engine.broadcaster()->bundle_end();
 		_engine.maid()->push(_patch_node_listnode);
 	} else if (_patch_port_listnode) {
@@ -196,7 +196,7 @@ DeleteEvent::post_process()
 		_engine.broadcaster()->bundle_begin();
 		if (_disconnect_event)
 			_disconnect_event->post_process();
-		_engine.broadcaster()->send_destroyed(_path);
+		_engine.broadcaster()->send_deleted(_path);
 		_engine.broadcaster()->bundle_end();
 		_engine.maid()->push(_patch_port_listnode);
 	} else {
diff --git a/src/engine/events/DeleteEvent.hpp b/src/engine/events/DeleteEvent.hpp
index d0fa43f1..05c47325 100644
--- a/src/engine/events/DeleteEvent.hpp
+++ b/src/engine/events/DeleteEvent.hpp
@@ -36,10 +36,19 @@ class DriverPort;
 class DisconnectAllEvent;
 class CompiledPatch;
 
-
-/** Delete a graph object.
- * WebDAV method DELETE (RFC4918 S9.6).
+/** \page methods
+ * <h2>DELETE</h2>
+ * From WebDAV (RFC4918 S9.6).
+ *
+ * Calling DELETE on an object will remove that object from the engine
+ * (i.e. stop executing it) and destroy it.
  *
+ * \li All properties of the object are lost
+ * \li All references to the object are lost (e.g. the parent's reference to
+ *     this child is lost, any connections to the object are removed, etc.)
+ */
+
+/** DELETE a graph object (see \ref methods).
  * \ingroup engine
  */
 class DeleteEvent : public QueuedEvent
diff --git a/src/engine/events/MoveEvent.hpp b/src/engine/events/MoveEvent.hpp
index f55d70b1..7b77439f 100644
--- a/src/engine/events/MoveEvent.hpp
+++ b/src/engine/events/MoveEvent.hpp
@@ -26,10 +26,17 @@ namespace Ingen {
 
 class PatchImpl;
 
-
-/** Move a graph object to a new path.
- * WebDAV method MOVE (RFC4918 S9.9).
+/** \page methods
+ * <h2>MOVE</h2>
+ * From WebDAV (RFC4918 S9.9).
+ *
+ * Calling MOVE on an object removes it from its current location
+ * and inserts it at a new one in a single operation.
  *
+ * MOVE to a path with a different parent is currently not supported.
+ */
+
+/** MOVE a graph object to a new path (see \ref methods).
  * \ingroup engine
  */
 class MoveEvent : public QueuedEvent