From d4f7ead7e77d3556afda76b2a58a941de0a19fb9 Mon Sep 17 00:00:00 2001
From: falkTX <falktx@gmail.com>
Date: Mon, 2 Dec 2013 01:23:48 +0000
Subject: [PATCH] Add some more inline code docs

---
 source/backend/CarlaBackend.h | 52 +++++++++++++++++++++--------------
 source/carla_backend.py       | 45 +++++++++++++++++++++++++++++-
 2 files changed, 75 insertions(+), 22 deletions(-)

diff --git a/source/backend/CarlaBackend.h b/source/backend/CarlaBackend.h
index 6e080703c..f263d601c 100644
--- a/source/backend/CarlaBackend.h
+++ b/source/backend/CarlaBackend.h
@@ -1013,33 +1013,37 @@ typedef void (*EngineCallbackFunc)(void* ptr, EngineCallbackOpcode action, unsig
  */
 typedef struct _ParameterData {
     /*!
-     *
+     * Index as seen by Carla.
      */
     int32_t index;
 
     /*!
-     *
+     * Real index as seen by plugins.
      */
     int32_t rindex;
 
     /*!
-     *
+     * This parameter hints.
+     * @see ParameterHints
      */
     unsigned int hints;
 
     /*!
-     *
+     * Currently mapped MIDI CC.\n
+     * A value lower than 0 means invalid or unused.\n
+     * Maximum allowed value is 95 (0x5F).
      */
     int16_t midiCC;
 
     /*!
-     *
+     * Currently mapped MIDI channel.\n
+     * Counts from 0 to 15.
      */
     uint8_t midiChannel;
 
 #ifdef __cplusplus
     /*!
-     *
+     * C++ constructor.
      */
     _ParameterData() noexcept
         : index(PARAMETER_NULL),
@@ -1070,7 +1074,7 @@ typedef struct _ParameterRanges {
     float max;
 
     /*!
-     * Regular step value.
+     * Regular, single step value.
      */
     float step;
 
@@ -1086,7 +1090,7 @@ typedef struct _ParameterRanges {
 
 #ifdef __cplusplus
     /*!
-     *
+     * C++ constructor.
      */
     _ParameterRanges() noexcept
         : def(0.0f),
@@ -1097,7 +1101,7 @@ typedef struct _ParameterRanges {
           stepLarge(0.1f) {}
 
     /*!
-     * Fix default value range.
+     * Fix default value within range.
      */
     void fixDefault() noexcept
     {
@@ -1116,7 +1120,7 @@ typedef struct _ParameterRanges {
     }
 
     /*!
-     *
+     * Get a fixed value within range.
      */
     float getFixedValue(const float& value) const noexcept
     {
@@ -1142,7 +1146,7 @@ typedef struct _ParameterRanges {
     }
 
     /*!
-     * Get a value normalized to 0.0<->1.0, but fix range first.
+     * Get a value normalized to 0.0<->1.0, fixed within range.
      */
     float getFixedAndNormalizedValue(const float& value) const noexcept
     {
@@ -1176,23 +1180,23 @@ typedef struct _ParameterRanges {
  */
 typedef struct _MidiProgramData {
     /*!
-     *
+     * MIDI bank.
      */
     uint32_t bank;
 
     /*!
-     *
+     * MIDI program.
      */
     uint32_t program;
 
     /*!
-     *
+     * Midi program name.
      */
     const char* name;
 
 #ifdef __cplusplus
     /*!
-     *
+     * C++ constructor.
      */
     _MidiProgramData() noexcept
         : bank(0),
@@ -1223,6 +1227,9 @@ typedef struct _CustomData {
     const char* value;
 
 #ifdef __cplusplus
+    /*!
+     * C++ constructor.
+     */
     _CustomData() noexcept
         : type(nullptr),
           key(nullptr),
@@ -1235,23 +1242,26 @@ typedef struct _CustomData {
  */
 typedef struct _EngineDriverDeviceInfo {
     /*!
-     *
+     * This driver device hints.
+     * @see EngineDriverHints
      */
     unsigned int hints;
 
     /*!
-     *
+     * Available buffer sizes.\n
+     * Terminated with 0.
      */
-    const uint32_t* bufferSizes; // terminated with 0
+    const uint32_t* bufferSizes;
 
     /*!
-     *
+     * Available sample rates.\n
+     * Terminated with 0.0.
      */
-    const double* sampleRates;   // terminated with 0.0
+    const double* sampleRates;
 
 #ifdef __cplusplus
     /*!
-     *
+     * C++ constructor.
      */
     _EngineDriverDeviceInfo()
         : hints(0x0),
diff --git a/source/carla_backend.py b/source/carla_backend.py
index d680b5596..fa63dbf16 100644
--- a/source/carla_backend.py
+++ b/source/carla_backend.py
@@ -722,46 +722,89 @@ EngineCallbackFunc = CFUNCTYPE(None, c_void_p, c_enum, c_uint, c_int, c_int, c_f
 # Parameter data.
 class ParameterData(Structure):
     _fields_ = [
-        ("type", c_enum),
+        # Index as seen by Carla.
         ("index", c_int32),
+
+        # Real index as seen by plugins.
         ("rindex", c_int32),
+
+        # This parameter hints.
+        # @see ParameterHints
         ("hints", c_uint),
+
+        # Currently mapped MIDI CC.
+        # A value lower than 0 means invalid or unused.
+        # Maximum allowed value is 95 (0x5F).
         ("midiCC", c_int16),
+
+        # Currently mapped MIDI channel.
+        # Counts from 0 to 15.
         ("midiChannel", c_uint8)
     ]
 
 # Parameter ranges.
 class ParameterRanges(Structure):
     _fields_ = [
+        # Default value.
         ("def", c_float),
+
+        # Minimum value.
         ("min", c_float),
+
+        # Maximum value.
         ("max", c_float),
+
+        # Regular, single step value.
         ("step", c_float),
+
+        # Small step value.
         ("stepSmall", c_float),
+
+        # Large step value.
         ("stepLarge", c_float)
     ]
 
 # MIDI Program data.
 class MidiProgramData(Structure):
     _fields_ = [
+        # MIDI bank.
         ("bank", c_uint32),
+
+        # MIDI program.
         ("program", c_uint32),
+
+        # MIDI program name.
         ("name", c_char_p)
     ]
 
 # Custom data, for saving key:value 'dictionaries'.
 class CustomData(Structure):
     _fields_ = [
+        # Value type, in URI form.
+        # @see CustomDataTypes
         ("type", c_char_p),
+
+        # Key.
+        # @see CustomDataKeys
         ("key", c_char_p),
+
+        # Value.
         ("value", c_char_p)
     ]
 
 # Engine driver device information.
 class EngineDriverDeviceInfo(Structure):
     _fields_ = [
+        # This driver device hints.
+        # @see EngineDriverHints
         ("hints", c_uint),
+
+        # Available buffer sizes.
+        # Terminated with 0.
         ("bufferSizes", POINTER(c_uint32)),
+
+        # Available sample rates.
+        # Terminated with 0.0.
         ("sampleRates", POINTER(c_double))
     ]