Update code docs

doc/Carla-TODO

@@ -91,3 +91,17 @@ LinuxSampler:
  - multi-program
  - 16outs (depends on multi-program)
  - proper buffer-size/sample-rate change
+
+# ----------------------------------------------------------------------------
+# current work
+
+BACKEND:
+ - cleanup API, document everything properly (tested with doxygen)
+ - apply API docs to python code as well (TODO: use proper predefined pydoc style)
+
+FRONTEND:
+ - fix things to new cleanup API
+ - share code as much as possible
+
+OTHER:
+ - create tests for all utils code

source/backend/CarlaBackend.h

@@ -45,6 +45,9 @@ CARLA_BACKEND_START_NAMESPACE
  * @{
  */
 
+// ------------------------------------------------------------------------------------------------------------
+// Carla Backend API (base definitions)
+
 /*!
  * Maximum default number of loadable plugins.
  */
@@ -66,6 +69,9 @@ const unsigned int MAX_PATCHBAY_PLUGINS = 255;
  */
 const unsigned int MAX_DEFAULT_PARAMETERS = 200;
 
+// ------------------------------------------------------------------------------------------------------------
+// Engine Driver Device Hints
+
 /*!
  * @defgroup EngineDriverHints Engine Driver Device Hints
  *
@@ -93,6 +99,9 @@ const unsigned int ENGINE_DRIVER_DEVICE_VARIABLE_SAMPLE_RATE = 0x4;
 
 /** @} */
 
+// ------------------------------------------------------------------------------------------------------------
+// Plugin Hints
+
 /*!
  * @defgroup PluginHints Plugin Hints
  *
@@ -145,11 +154,14 @@ const unsigned int PLUGIN_CAN_PANNING = 0x80;
 
 /** @} */
 
+// ------------------------------------------------------------------------------------------------------------
+// Plugin Options
+
 /*!
  * @defgroup PluginOptions Plugin Options
  *
  * Various plugin options.
- * @see CarlaPlugin::getOptionsAvailable(), CarlaPlugin::getOptionsEnabled() and carla_get_plugin_info()
+ * @see CarlaPlugin::getOptionsAvailable(), CarlaPlugin::getOptionsEnabled(), carla_get_plugin_info() and carla_set_option()
  * @{
  */
 
@@ -200,6 +212,9 @@ const unsigned int PLUGIN_OPTION_SEND_ALL_SOUND_OFF = 0x100;
 
 /** @} */
 
+// ------------------------------------------------------------------------------------------------------------
+// Parameter Hints
+
 /*!
  * @defgroup ParameterHints Parameter Hints
  *
@@ -266,6 +281,9 @@ const unsigned int PARAMETER_USES_CUSTOM_TEXT = 0x400;
 
 /** @} */
 
+// ------------------------------------------------------------------------------------------------------------
+// Patchbay Port Hints
+
 /*!
  * @defgroup PatchbayPortHints Patchbay Port Hints
  *
@@ -296,6 +314,9 @@ const unsigned int PATCHBAY_PORT_TYPE_MIDI = 0x8;
 
 /** @} */
 
+// ------------------------------------------------------------------------------------------------------------
+// Custom Data Types
+
 /*!
  * @defgroup CustomDataTypes Custom Data Types
  *
@@ -322,6 +343,9 @@ const char* const CUSTOM_DATA_TYPE_STRING = "http://kxstudio.sf.net/ns/carla/str
 
 /** @} */
 
+// ------------------------------------------------------------------------------------------------------------
+// Custom Data Keys
+
 /*!
  * @defgroup CustomDataKeys Custom Data Keys
  *
@@ -352,6 +376,9 @@ const char* const CUSTOM_DATA_KEY_UI_VISIBLE = "CarlaUiVisible";
 
 /** @} */
 
+// ------------------------------------------------------------------------------------------------------------
+// Binary Type
+
 /*!
  * The binary type of a plugin.
  */
@@ -388,6 +415,9 @@ typedef enum {
 
 } BinaryType;
 
+// ------------------------------------------------------------------------------------------------------------
+// Plugin Type
+
 /*!
  * Plugin type.
  * Some files are handled as if they were plugins.
@@ -451,6 +481,9 @@ typedef enum {
 
 } PluginType;
 
+// ------------------------------------------------------------------------------------------------------------
+// Plugin Category
+
 /*!
  * Plugin category, which describes the functionality of a plugin.
  */
@@ -507,6 +540,9 @@ typedef enum {
 
 } PluginCategory;
 
+// ------------------------------------------------------------------------------------------------------------
+// Internal Parameter Index
+
 /*!
  * Special parameters used internally in Carla.\n
  * Plugins do not know about their existence.
@@ -566,6 +602,9 @@ typedef enum {
 
 } InternalParameterIndex;
 
+// ------------------------------------------------------------------------------------------------------------
+// Engine Callback Opcode
+
 /*!
  * Engine callback opcodes.\n
  * Front-ends must never block indefinitely during a callback.
@@ -835,6 +874,9 @@ typedef enum {
 
 } EngineCallbackOpcode;
 
+// ------------------------------------------------------------------------------------------------------------
+// Engine Option
+
 /*!
  * Engine options.
  * @see CarlaEngine::getOptions(), CarlaEngine::setOption() and carla_set_engine_option()
@@ -938,6 +980,9 @@ typedef enum {
 
 } EngineOption;
 
+// ------------------------------------------------------------------------------------------------------------
+// Engine Process Mode
+
 /*!
  * Engine process mode.
  * @see ENGINE_OPTION_PROCESS_MODE
@@ -973,8 +1018,11 @@ typedef enum {
 
 } EngineProcessMode;
 
+// ------------------------------------------------------------------------------------------------------------
+// Engine Transport Mode
+
 /*!
- * Engine transport mode
+ * Engine transport mode.
  * @see ENGINE_OPTION_TRANSPORT_MODE
  */
 typedef enum {
@@ -1001,12 +1049,15 @@ typedef enum {
 
 } EngineTransportMode;
 
+// ------------------------------------------------------------------------------------------------------------
+// Carla Backend API (C stuff)
+
 /*!
  * Engine callback function.\n
  * Front-ends must never block indefinitely during a callback.
  * @see EngineCallbackOpcode, CarlaEngine::setCallback() and carla_set_engine_callback()
  */
-typedef void (*EngineCallbackFunc)(void* ptr, EngineCallbackOpcode action, unsigned int pluginId, int value1, int value2, float value3, const char* valueStr);
+typedef void (*EngineCallbackFunc)(void* ptr, EngineCallbackOpcode action, uint pluginId, int value1, int value2, float value3, const char* valueStr);
 
 /*!
  * Parameter data.

source/backend/CarlaHost.h

@@ -51,6 +51,9 @@ using CarlaBackend::CarlaPlugin;
  * @{
  */
 
+// ------------------------------------------------------------------------------------------------------------
+// File Callback Opcode
+
 /*!
  * File callback opcodes.\n
  * Front-ends must always block-wait for user input.
@@ -75,6 +78,9 @@ typedef enum {
 
 } FileCallbackOpcode;
 
+// ------------------------------------------------------------------------------------------------------------
+// Carla Host API (C stuff)
+
 /*!
  * File callback function.
  * @see FileCallbackOpcode
@@ -463,6 +469,9 @@ typedef struct _CarlaTransportInfo {
 #endif
 } CarlaTransportInfo;
 
+// ------------------------------------------------------------------------------------------------------------
+// Carla Host API (C functions)
+
 /*!
  * Get the complete license text of used third-party code and features.\n
  * Returned string is in basic html format.
@@ -515,10 +524,10 @@ CARLA_EXPORT const CarlaNativePluginInfo* carla_get_internal_plugin_info(unsigne
 
 #ifdef __cplusplus
 /*!
- * Get the currently used Host engine.
+ * Get the currently used engine, maybe be NULL.
  * @note C++ only
  */
-CARLA_EXPORT CarlaEngine* carla_get_host_engine();
+CARLA_EXPORT const CarlaEngine* carla_get_engine();
 #endif
 
 /*!
@@ -610,12 +619,17 @@ CARLA_EXPORT bool carla_load_project(const char* filename);
 CARLA_EXPORT bool carla_save_project(const char* filename);
 
 /*!
- * Connect patchbay ports \a portA and \a portB.
+ * Connect two patchbay ports.
+ * @param portA Output port
+ * @param portB Input port
+ * @see ENGINE_CALLBACK_PATCHBAY_CONNECTION_ADDED
  */
 CARLA_EXPORT bool carla_patchbay_connect(int portA, int portB);
 
 /*!
- * Disconnect patchbay connection \a connectionId.
+ * Disconnect two patchbay ports.
+ * @param connectionId Connection Id
+ * @see ENGINE_CALLBACK_PATCHBAY_CONNECTION_REMOVED
  */
 CARLA_EXPORT bool carla_patchbay_disconnect(int connectionId);
 
@@ -635,7 +649,8 @@ CARLA_EXPORT void carla_transport_play();
 CARLA_EXPORT void carla_transport_pause();
 
 /*!
- * Relocate the engine transport to \a frames.
+ * Relocate the engine transport to a specific frame.
+ * @param frames Frame to relocate to.
  */
 CARLA_EXPORT void carla_transport_relocate(uint32_t frames);
 

source/carla_backend.py

@@ -134,6 +134,8 @@ MAX_DEFAULT_PARAMETERS = 200
 
 # ------------------------------------------------------------------------------------------------------------
 # Engine Driver Device Hints
+# Various engine driver device hints.
+# @see carla_get_engine_driver_device_info()
 
 # Engine driver device has custom control-panel.
 ENGINE_DRIVER_DEVICE_HAS_CONTROL_PANEL = 0x1
@@ -148,6 +150,8 @@ ENGINE_DRIVER_DEVICE_VARIABLE_SAMPLE_RATE = 0x4
 
 # ------------------------------------------------------------------------------------------------------------
 # Plugin Hints
+# Various plugin hints.
+# @see carla_get_plugin_info()
 
 # Plugin is a bridge.
 # This hint is required because "bridge" itself is not a plugin type.
@@ -177,6 +181,8 @@ PLUGIN_CAN_PANNING = 0x80
 
 # ------------------------------------------------------------------------------------------------------------
 # Plugin Options
+# Various plugin options.
+# @see carla_get_plugin_info() and carla_set_option()
 
 # Use constant/fixed-size audio buffers.
 PLUGIN_OPTION_FIXED_BUFFERS = 0x001
@@ -207,6 +213,8 @@ PLUGIN_OPTION_SEND_ALL_SOUND_OFF = 0x100
 
 # ------------------------------------------------------------------------------------------------------------
 # Parameter Hints
+# Various parameter hints.
+# @see CarlaPlugin::getParameterData() and carla_get_parameter_data()
 
 # Parameter is input.
 # When this hint is not set, parameter is assumed to be output.
@@ -245,6 +253,7 @@ PARAMETER_USES_CUSTOM_TEXT = 0x400
 
 # ------------------------------------------------------------------------------------------------------------
 # Patchbay Port Hints
+# Various patchbay port hints.
 
 # Patchbay port is input.
 # When this hint is not set, port is assumed to be output.
@@ -261,6 +270,8 @@ PATCHBAY_PORT_TYPE_MIDI = 0x8
 
 # ------------------------------------------------------------------------------------------------------------
 # Custom Data Types
+# These types define how the value in the CustomData struct is stored.
+# @see CustomData.type
 
 # Boolean string type URI.
 # Only "true" and "false" are valid values.
@@ -274,6 +285,8 @@ CUSTOM_DATA_TYPE_STRING = "http://kxstudio.sf.net/ns/carla/string"
 
 # ------------------------------------------------------------------------------------------------------------
 # Custom Data Keys
+# Pre-defined keys used internally in Carla.
+# @see CustomData.key
 
 # Plugin options key.
 CUSTOM_DATA_KEY_PLUGIN_OPTIONS = "CarlaPluginOptions"
@@ -289,6 +302,7 @@ CUSTOM_DATA_KEY_UI_VISIBLE = "CarlaUiVisible"
 
 # ------------------------------------------------------------------------------------------------------------
 # Binary Type
+# The binary type of a plugin.
 
 # Null binary type.
 BINARY_NONE = 0
@@ -310,6 +324,8 @@ BINARY_OTHER = 5
 
 # ------------------------------------------------------------------------------------------------------------
 # Plugin Type
+# Plugin type.
+# Some files are handled as if they were plugins.
 
 # Null plugin type.
 PLUGIN_NONE = 0
@@ -347,6 +363,7 @@ PLUGIN_SFZ = 10
 
 # ------------------------------------------------------------------------------------------------------------
 # Plugin Category
+# Plugin category, which describes the functionality of a plugin.
 
 # Null plugin category.
 PLUGIN_CATEGORY_NONE = 0
@@ -379,7 +396,9 @@ PLUGIN_CATEGORY_UTILITY = 8
 PLUGIN_CATEGORY_OTHER = 9
 
 # ------------------------------------------------------------------------------------------------------------
-# Internal Parameters Index
+# Internal Parameter Index
+# Special parameters used internally in Carla.
+# Plugins do not know about their existence.
 
 # Null parameter.
 PARAMETER_NULL = -1
@@ -417,6 +436,9 @@ PARAMETER_MAX = -9
 
 # ------------------------------------------------------------------------------------------------------------
 # Engine Callback Opcode
+# Engine callback opcodes.
+# Front-ends must never block indefinitely during a callback.
+# @see EngineCallbackFunc and carla_set_engine_callback()
 
 # Debug.
 # This opcode is undefined and used only for testing purposes.
@@ -607,6 +629,8 @@ ENGINE_CALLBACK_QUIT = 36
 
 # ------------------------------------------------------------------------------------------------------------
 # Engine Option
+# Engine options.
+# @see carla_set_engine_option()
 
 # Debug.
 # This option is undefined and used only for testing purposes.
@@ -676,6 +700,8 @@ ENGINE_OPTION_PATH_RESOURCES = 14
 
 # ------------------------------------------------------------------------------------------------------------
 # Engine Process Mode
+# Engine process mode.
+# @see ENGINE_OPTION_PROCESS_MODE
 
 # Single client mode.
 # Inputs and outputs are added dynamically as needed by plugins.
@@ -697,6 +723,8 @@ ENGINE_PROCESS_MODE_BRIDGE = 4
 
 # ------------------------------------------------------------------------------------------------------------
 # Engine Transport Mode
+# Engine transport mode.
+# @see ENGINE_OPTION_TRANSPORT_MODE
 
 # Internal transport mode.
 ENGINE_TRANSPORT_MODE_INTERNAL = 0
@@ -853,6 +881,9 @@ PyEngineDriverDeviceInfo = {
 
 # ------------------------------------------------------------------------------------------------------------
 # File Callback Opcode
+# File callback opcodes.
+# Front-ends must always block-wait for user input.
+# @see FileCallbackFunc and carla_set_file_callback()
 
 # Debug.
 # This opcode is undefined and used only for testing purposes.
@@ -1208,27 +1239,41 @@ class Host(object):
     def save_project(self, filename):
         return bool(self.lib.carla_save_project(filename.encode("utf-8")))
 
+    # Connect two patchbay ports.
+    # @param portA Output port
+    # @param portB Input port
+    # @see ENGINE_CALLBACK_PATCHBAY_CONNECTION_ADDED
     def patchbay_connect(self, portIdA, portIdB):
         return bool(self.lib.carla_patchbay_connect(portIdA, portIdB))
 
+    # Disconnect two patchbay ports.
+    # @param connectionId Connection Id
+    # @see ENGINE_CALLBACK_PATCHBAY_CONNECTION_REMOVED
     def patchbay_disconnect(self, connectionId):
         return bool(self.lib.carla_patchbay_disconnect(connectionId))
 
+    # Force the engine to resend all patchbay clients, ports and connections again.
     def patchbay_refresh(self):
         return bool(self.lib.carla_patchbay_refresh())
 
+    # Start playback of the engine transport.
     def transport_play(self):
         self.lib.carla_transport_play()
 
+    # Pause the engine transport.
     def transport_pause(self):
         self.lib.carla_transport_pause()
 
+    # Relocate the engine transport to a specific frame.
+    # @param frames Frame to relocate to.
     def transport_relocate(self, frames):
         self.lib.carla_transport_relocate(frames)
 
+    # Get the current transport frame.
     def get_current_transport_frame(self):
         return bool(self.lib.carla_get_current_transport_frame())
 
+    # Get the engine transport information.
     def get_transport_info(self):
         return structToDict(self.lib.carla_get_transport_info().contents)
 
@@ -1406,18 +1451,6 @@ class Host(object):
     def get_sample_rate(self):
         return self.lib.carla_get_sample_rate()
 
-    def nsm_announce(self, url, appName_, pid):
-        self.lib.carla_nsm_announce(url.encode("utf-8"), appName_.encode("utf-8"), pid)
-
-    def nsm_ready(self):
-        self.lib.carla_nsm_ready()
-
-    def nsm_reply_open(self):
-        self.lib.carla_nsm_reply_open()
-
-    def nsm_reply_save(self):
-        self.lib.carla_nsm_reply_save()
-
     def _init(self, libName):
         self.lib = cdll.LoadLibrary(libName)
 
@@ -1669,17 +1702,3 @@ class Host(object):
 
         self.lib.carla_get_host_osc_url_udp.argtypes = None
         self.lib.carla_get_host_osc_url_udp.restype = c_char_p
-
-        return
-
-        self.lib.carla_nsm_announce.argtypes = [c_char_p, c_char_p, c_int]
-        self.lib.carla_nsm_announce.restype = None
-
-        self.lib.carla_nsm_ready.argtypes = None
-        self.lib.carla_nsm_ready.restype = None
-
-        self.lib.carla_nsm_reply_open.argtypes = None
-        self.lib.carla_nsm_reply_open.restype = None
-
-        self.lib.carla_nsm_reply_save.argtypes = None
-        self.lib.carla_nsm_reply_save.restype = None