Update OSC documentation.

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

2 files changed, 132 insertions, 108 deletions

diff --git a/src/engine/OSCClientSender.cpp b/src/engine/OSCClientSender.cpp
index 020fb922..0d3c5cf6 100644
--- a/src/engine/OSCClientSender.cpp
+++ b/src/engine/OSCClientSender.cpp
@@ -27,6 +27,7 @@
 #include "NodeImpl.hpp"
 #include "OSCClientSender.hpp"
 #include "PatchImpl.hpp"
+
 #include "PluginImpl.hpp"
 #include "PortImpl.hpp"
 #include "ingen/ClientInterface.hpp"
@@ -38,16 +39,17 @@ using namespace Raul;
 namespace Ingen {
 namespace Engine {
 
-/*! \page client_osc_namespace Client OSC Namespace Documentation
+/** @page client_osc_namespace Client OSC Namespace Documentation
  *
  * <p>These are the commands the client recognizes.  All monitoring of
  * changes in the engine happens via these commands.</p>
  */
 
-/** \page client_osc_namespace
+/** @page client_osc_namespace
  * <h2>/ok</h2>
- * \arg \b response-id (int) - Request ID this is a response to
+ * @arg @p response-id :: Integer
  *
+ * @par
  * Successful response to some command.
  */
 void
@@ -56,17 +58,20 @@ OSCClientSender::response_ok(int32_t id)
 	if (!_enabled)
 		return;
 
+
+	
 	if (lo_send(_address, "/ok", "i", id, LO_ARGS_END) < 0) {
 		Raul::error << "Unable to send OK " << id << "! ("
 			<< lo_address_errstr(_address) << ")" << endl;
 	}
 }
 
-/** \page client_osc_namespace
+/** @page client_osc_namespace
  * <h2>/error</h2>
- * \arg \b response-id (int) - Request ID this is a response to
- * \arg \b message (string) - Error message (natural language text)
+ * @arg @p response-id :: Integer
+ * @arg @p message :: String
  *
+ * @par
  * Unsuccessful response to some command.
  */
 void
@@ -81,13 +86,13 @@ OSCClientSender::response_error(int32_t id, const std::string& msg)
 	}
 }
 
-/** \page client_osc_namespace
+/** @page client_osc_namespace
  * <h2>/error</h2>
- * \arg \b message (string) - Error message (natural language text)
+ * @arg @p message :: String
  *
- * 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.
+ * @par
+ * Notification that an error has occurred.  This is for notification of errors
+ * that aren't a direct response to a user command, i.e. "unexpected" errors.
  */
 void
 OSCClientSender::error(const std::string& msg)
@@ -95,14 +100,15 @@ OSCClientSender::error(const std::string& msg)
 	send("/error", "s", msg.c_str(), LO_ARGS_END);
 }
 
-/** \page client_osc_namespace
+/** @page client_osc_namespace
  * <h2>/put</h2>
- * \arg \b path (string) - Path of object
- * \arg \b predicate
- * \arg \b value
- * \arg \b ...
+ * @arg @p path :: String
+ * @arg @p predicate :: URI String
+ * @arg @p value
+ * @arg @p ...
  *
- * PUT a set of properties to a path (see \ref methods).
+ * @par
+ * PUT a set of properties to a path.
  */
 void
 OSCClientSender::put(const Raul::URI&            path,
@@ -127,12 +133,13 @@ OSCClientSender::delta(const Raul::URI&            path,
 	warn << "FIXME: OSC DELTA" << endl;
 }
 
-/** \page client_osc_namespace
+/** @page client_osc_namespace
  * <h2>/move</h2>
- * \arg \b old-path (string) - Old path of object
- * \arg \b new-path (string) - New path of object
+ * @arg @p old-path :: String
+ * @arg @p new-path :: String
  *
- * MOVE an object to a new path (see \ref methods).
+ * @par
+ * MOVE an object to a new path.
  * The new path will have the same parent as the old path.
  */
 void
@@ -141,11 +148,12 @@ OSCClientSender::move(const Path& old_path, const Path& new_path)
 	send("/move", "ss", old_path.c_str(), new_path.c_str(), LO_ARGS_END);
 }
 
-/** \page client_osc_namespace
+/** @page client_osc_namespace
  * <h2>/delete</h2>
- * \arg \b path (string) - Path of object (which no longer exists)
+ * @arg @p path :: String
  *
- * DELETE an object (see \ref methods).
+ * @par
+ * DELETE an object.
  */
 void
 OSCClientSender::del(const URI& uri)
@@ -153,11 +161,12 @@ OSCClientSender::del(const URI& uri)
 	send("/delete", "s", uri.c_str(), LO_ARGS_END);
 }
 
-/** \page client_osc_namespace
+/** @page client_osc_namespace
  * <h2>/connect</h2>
- * \arg \b src-path (string) - Path of the source port
- * \arg \b dst-path (string) - Path of the destination port
+ * @arg @p src-path :: String
+ * @arg @p dst-path :: String
  *
+ * @par
  * Notification a new connection has been made.
  */
 void
@@ -167,11 +176,12 @@ OSCClientSender::connect(const Path& src_port_path,
 	send("/connect", "ss", src_port_path.c_str(), dst_port_path.c_str(), LO_ARGS_END);
 }
 
-/** \page client_osc_namespace
+/** @page client_osc_namespace
  * <h2>/disconnect</h2>
- * \arg \b src-path (string) - Path of the source port
- * \arg \b dst-path (string) - Path of the destination port
+ * @arg @p src-path :: String
+ * @arg @p dst-path :: String
  *
+ * @par
  * Notification a connection has been unmade.
  */
 void
@@ -181,12 +191,13 @@ OSCClientSender::disconnect(const Path& src_port_path,
 	send("/disconnect", "ss", src_port_path.c_str(), dst_port_path.c_str(), LO_ARGS_END);
 }
 
-/** \page client_osc_namespace
+/** @page client_osc_namespace
  * <h2>/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)
+ * @arg @p path :: String
+ * @arg @p key :: URI String
+ * @arg @p value
  *
+ * @par
  * Notification of a property.
  */
 void
@@ -201,10 +212,11 @@ OSCClientSender::set_property(const URI& path,
 	send_message("/set_property", m);
 }
 
-/** \page client_osc_namespace
+/** @page client_osc_namespace
  * <h2>/activity</h2>
- * \arg \b path (string) - Path of object
+ * @arg @p path :: String
  *
+ * @par
  * Notification of "activity" (e.g. port message blinkenlights).
  */
 void
diff --git a/src/engine/OSCEngineReceiver.cpp b/src/engine/OSCEngineReceiver.cpp
index 45af1d97..fdb0bcc4 100644
--- a/src/engine/OSCEngineReceiver.cpp
+++ b/src/engine/OSCEngineReceiver.cpp
@@ -47,14 +47,14 @@ using namespace Raul;
 namespace Ingen {
 namespace Engine {
 
-/*! \page engine_osc_namespace Engine OSC Namespace Documentation
+/** @page engine_osc_namespace Engine OSC Namespace Documentation
  *
  * <p>These are the commands the engine recognizes.  A client can control every
  * aspect of the engine entirely with these commands.</p>
  *
  * <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.
+ * See the "Client OSC Namespace Documentation" for details.</p>
  */
 
 OSCEngineReceiver::OSCEngineReceiver(Engine& engine, size_t queue_size, uint16_t port)
@@ -237,11 +237,9 @@ OSCEngineReceiver::error_cb(int num, const char* msg, const char* path)
 	error << " (" << msg << ")" << endl;
 }
 
-/** \page engine_osc_namespace
+/** @page engine_osc_namespace
  * <h2>/ping</h2>
- * \arg \b response-id (integer)
- *
- * Reply to sender immediately with a successful response.
+ * @arg @p response-id :: Integer
  */
 int
 OSCEngineReceiver::_ping_cb(const char* path, const char* types, lo_arg** argv, int argc, lo_message msg)
@@ -252,14 +250,15 @@ OSCEngineReceiver::_ping_cb(const char* path, const char* types, lo_arg** argv,
 	return 0;
 }
 
-/** \page engine_osc_namespace
+/** @page engine_osc_namespace
  * <h2>/ping_queued</h2>
- * \arg \b response-id (integer)
+ * @arg @p response-id :: Integer
  *
- * 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.
+ * @par
+ * 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)
@@ -268,13 +267,13 @@ OSCEngineReceiver::_ping_slow_cb(const char* path, const char* types, lo_arg** a
 	return 0;
 }
 
-/** \page engine_osc_namespace
+/** @page engine_osc_namespace
  * <h2>/register_client</h2>
- * \arg \b response-id (integer)
+ * @arg @p 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.
+ * @par
+ * Register a new client with the engine.  The incoming address will be
+ * used for the new registered client.
  */
 int
 OSCEngineReceiver::_register_client_cb(const char* path, const char* types, lo_arg** argv, int argc, lo_message msg)
@@ -291,10 +290,11 @@ OSCEngineReceiver::_register_client_cb(const char* path, const char* types, lo_a
 	return 0;
 }
 
-/** \page engine_osc_namespace
+/** @page engine_osc_namespace
  * <h2>/unregister_client</h2>
- * \arg \b response-id (integer)
+ * @arg @p response-id :: Integer
  *
+ * @par
  * Unregister a client.
  */
 int
@@ -309,11 +309,12 @@ OSCEngineReceiver::_unregister_client_cb(const char* path, const char* types, lo
 	return 0;
 }
 
-/** \page engine_osc_namespace
+/** @page engine_osc_namespace
  * <h2>/get</h2>
- * \arg \b response-id (integer)
- * \arg \b uri (string) - URI of object (patch, port, node, plugin) to send
+ * @arg @p response-id :: Integer
+ * @arg @p uri :: URI String
  *
+ * @par
  * Request all properties of an object.
  */
 int
@@ -323,15 +324,16 @@ OSCEngineReceiver::_get_cb(const char* path, const char* types, lo_arg** argv, i
 	return 0;
 }
 
-/** \page engine_osc_namespace
+/** @page engine_osc_namespace
  * <h2>/put</h2>
- * \arg \b response-id (integer)
- * \arg \b path (string) - Path of object
- * \arg \b predicate
- * \arg \b value
- * \arg \b ...
+ * @arg @p response-id :: Integer
+ * @arg @p path :: String
+ * @arg @p predicate :: URI String
+ * @arg @p value
+ * @arg @p ...
  *
- * PUT a set of properties to a path (see \ref methods).
+ * @par
+ * PUT a set of properties to a path.
  */
 int
 OSCEngineReceiver::_put_cb(const char* path, const char* types, lo_arg** argv, int argc, lo_message msg)
@@ -344,13 +346,14 @@ OSCEngineReceiver::_put_cb(const char* path, const char* types, lo_arg** argv, i
 	return 0;
 }
 
-/** \page engine_osc_namespace
+/** @page engine_osc_namespace
  * <h2>/move</h2>
- * \arg \b response-id (integer)
- * \arg \b old-path - Object's path
- * \arg \b new-path - Object's new path
+ * @arg @p response-id :: Integer
+ * @arg @p old-path :: String
+ * @arg @p new-path :: String
  *
- * MOVE an object to a new path (see \ref methods).
+ * @par
+ * MOVE an object to a new path.
  */
 int
 OSCEngineReceiver::_move_cb(const char* path, const char* types, lo_arg** argv, int argc, lo_message msg)
@@ -362,12 +365,13 @@ OSCEngineReceiver::_move_cb(const char* path, const char* types, lo_arg** argv,
 	return 0;
 }
 
-/** \page engine_osc_namespace
- * <h2>/del</h2>
- * \arg \b response-id (integer)
- * \arg \b path (string) - Full path of the object
+/** @page engine_osc_namespace
+ * <h2>/delete</h2>
+ * @arg @p response-id :: Integer
+ * @arg @p path :: String
  *
- * DELETE an object (see \ref methods).
+ * @par
+ * DELETE an object.
  */
 int
 OSCEngineReceiver::_del_cb(const char* path, const char* types, lo_arg** argv, int argc, lo_message msg)
@@ -378,12 +382,13 @@ OSCEngineReceiver::_del_cb(const char* path, const char* types, lo_arg** argv, i
 	return 0;
 }
 
-/** \page engine_osc_namespace
+/** @page engine_osc_namespace
  * <h2>/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
+ * @arg @p response-id :: Integer
+ * @arg @p src-port-path :: String
+ * @arg @p dst-port-path :: String
  *
+ * @par
  * Connect two ports (which must be in the same patch).
  */
 int
@@ -396,12 +401,13 @@ OSCEngineReceiver::_connect_cb(const char* path, const char* types, lo_arg** arg
 	return 0;
 }
 
-/** \page engine_osc_namespace
+/** @page engine_osc_namespace
  * <h2>/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
+ * @arg @p response-id :: Integer
+ * @arg @p src-port-path :: String
+ * @arg @p dst-port-path :: String
  *
+ * @par
  * Disconnect two ports.
  */
 int
@@ -414,12 +420,13 @@ OSCEngineReceiver::_disconnect_cb(const char* path, const char* types, lo_arg**
 	return 0;
 }
 
-/** \page engine_osc_namespace
+/** @page engine_osc_namespace
  * <h2>/disconnect_all</h2>
- * \arg \b response-id (integer)
- * \arg \b patch-path (string) - The (parent) patch in which to disconnect object.
- * \arg \b object-path (string) - Full path of object.
+ * @arg @p response-id :: Integer
+ * @arg @p patch-path :: String
+ * @arg @p object-path :: String
  *
+ * @par
  * Disconnect all connections to/from a node/port.
  */
 int
@@ -432,13 +439,14 @@ OSCEngineReceiver::_disconnect_all_cb(const char* path, const char* types, lo_ar
 	return 0;
 }
 
-/** \page engine_osc_namespace
+/** @page engine_osc_namespace
  * <h2>/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)
+ * @arg @p response-id :: Integer
+ * @arg @p node-path :: String
+ * @arg @p note-num (int)
+ * @arg @p velocity (int)
  *
+ * @par
  * Trigger a note-on, just as if it came from MIDI.
  */
 int
@@ -454,12 +462,13 @@ OSCEngineReceiver::_note_on_cb(const char* path, const char* types, lo_arg** arg
 	return 0;
 }
 
-/** \page engine_osc_namespace
+/** @page engine_osc_namespace
  * <h2>/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)
+ * @arg @p response-id :: Integer
+ * @arg @p node-path :: String
+ * @arg @p note-num :: Integer
  *
+ * @par
  * Trigger a note-off, just as if it came from MIDI.
  */
 int
@@ -474,11 +483,12 @@ OSCEngineReceiver::_note_off_cb(const char* path, const char* types, lo_arg** ar
 	return 0;
 }
 
-/** \page engine_osc_namespace
+/** @page engine_osc_namespace
  * <h2>/all_notes_off</h2>
- * \arg \b response-id (integer)
- * \arg \b patch-path (string) - Patch of patch to send event to
+ * @arg @p response-id :: Integer
+ * @arg @p patch-path :: String
  *
+ * @par
  * Trigger a note-off for all voices, just as if it came from MIDI.
  */
 int
@@ -493,13 +503,14 @@ OSCEngineReceiver::_all_notes_off_cb(const char* path, const char* types, lo_arg
 	return 0;
 }
 
-/** \page engine_osc_namespace
+/** @page engine_osc_namespace
  * <h2>/set_property</h2>
- * \arg \b response-id (integer)
- * \arg \b object-path (string) - Full path of object to associate property with
- * \arg \b key (string) - URI for predicate of this property (e.g. "http://drobilla.net/ns/ingen#enabled")
- * \arg \b value (string) - Value of property
+ * @arg @p response-id :: Integer
+ * @arg @p uri :: URI String
+ * @arg @p key :: URI String
+ * @arg @p value :: String
  *
+ * @par
  * Set a property on a graph object.
  */
 int
@@ -517,11 +528,11 @@ OSCEngineReceiver::_set_property_cb(const char* path, const char* types, lo_arg*
 	return 0;
 }
 
-/** \page engine_osc_namespace
+/** @page engine_osc_namespace
  * <h2>/request_property</h2>
- * \arg \b response-id (integer)
- * \arg \b uri (string) - Subject
- * \arg \b key (string) - Predicate
+ * @arg @p response-id :: Integer
+ * @arg @p uri :: URI String
+ * @arg @p key :: URI String
  *
  * Request the value of a property on an object.
  */
@@ -537,6 +548,7 @@ OSCEngineReceiver::_request_property_cb(const char* path, const char* types, lo_
 
 //  Static Callbacks //
 
+
 // Display incoming OSC messages (for debugging purposes)
 int
 OSCEngineReceiver::generic_cb(const char* path, const char* types, lo_arg** argv, int argc, lo_message msg, void* user_data)