From bae987e6194d7ea48166e515e644a3658c3de0c0 Mon Sep 17 00:00:00 2001
From: Paul Walker <paul@pwjw.com>
Date: Mon, 18 Nov 2024 22:37:56 -0500
Subject: [PATCH] Add some of the feedback from the Auburn/DPlug port

basically expand some comments around ranges, meaning, and so on.
---
 include/clap/events.h     | 13 ++++++++++++-
 include/clap/ext/gui.h    | 11 +++++++++--
 include/clap/ext/params.h |  6 +++---
 3 files changed, 24 insertions(+), 6 deletions(-)

diff --git a/include/clap/events.h b/include/clap/events.h
index 198c7222..efcc2abb 100644
--- a/include/clap/events.h
+++ b/include/clap/events.h
@@ -9,7 +9,12 @@ extern "C" {
 #endif
 
 // event header
-// must be the first attribute of the event
+// All clap events start with an event header to determine the overall
+// size of the event and its type and space (a namespacing for types).
+// clap_event objects are contiguous regions of memory which can be copied
+// with a memcpy of `size` bytes starting at the top of the header. As
+// such, be very careful when desiginig clap events with internal pointers
+// and other non-value-types to consider the lifetime of those members.
 typedef struct clap_event_header {
    uint32_t size;     // event size including this header, eg: sizeof (clap_event_note)
    uint32_t time;     // sample offset within the buffer for this event
@@ -266,6 +271,12 @@ enum clap_transport_flags {
    CLAP_TRANSPORT_IS_WITHIN_PRE_ROLL = 1 << 7,
 };
 
+// clap_event_transport provides song position, tempo, and similar information
+// from the host to the plugin. There are two ways a host communicates these values.
+// In the `clap_process` structure sent to each processing block, the host must
+// provide a transport structure which indicates the available information at the
+// start of the block. If the host provides sample-accurate tempo or transport changes,
+// it can also provide subsequent inter-block transport updates by delivering a new event.
 typedef struct clap_event_transport {
    clap_event_header_t header;
 
diff --git a/include/clap/ext/gui.h b/include/clap/ext/gui.h
index 7704da91..d8d76eeb 100644
--- a/include/clap/ext/gui.h
+++ b/include/clap/ext/gui.h
@@ -13,6 +13,9 @@
 /// Embedding the window gives more control to the host, and feels more integrated.
 /// Floating window are sometimes the only option due to technical limitations.
 ///
+/// The Embedding protocol is by far the most common, supported by all hosts to date,
+/// and a plugin author should support at least that case.
+///
 /// Showing the GUI works as follow:
 ///  1. clap_plugin_gui->is_api_supported(), check what can work
 ///  2. clap_plugin_gui->create(), allocates gui resources
@@ -85,7 +88,10 @@ typedef struct clap_gui_resize_hints {
    bool can_resize_horizontally;
    bool can_resize_vertically;
 
-   // only if can resize horizontally and vertically
+   // if both horizontal and vertical resize are available, do we preserve the
+   // aspect ratio, and if so, what is the width x height aspect ratio to preserve.
+   // These flags are unused if can_resize_horizontally or vertically are false,
+   // and ratios are unused if preserve is false.
    bool     preserve_aspect_ratio;
    uint32_t aspect_ratio_width;
    uint32_t aspect_ratio_height;
@@ -94,7 +100,8 @@ typedef struct clap_gui_resize_hints {
 // Size (width, height) is in pixels; the corresponding windowing system extension is
 // responsible for defining if it is physical pixels or logical pixels.
 typedef struct clap_plugin_gui {
-   // Returns true if the requested gui api is supported
+   // Returns true if the requested gui api is supported, either in floating (plugin-created)
+   // or non-floating (embedded) mode.
    // [main-thread]
    bool(CLAP_ABI *is_api_supported)(const clap_plugin_t *plugin, const char *api, bool is_floating);
 
diff --git a/include/clap/ext/params.h b/include/clap/ext/params.h
index 33602634..2f857696 100644
--- a/include/clap/ext/params.h
+++ b/include/clap/ext/params.h
@@ -246,9 +246,9 @@ typedef struct clap_param_info {
    // '/' will be used as a separator to show a tree-like structure.
    char module[CLAP_PATH_SIZE];
 
-   double min_value;     // Minimum plain value
-   double max_value;     // Maximum plain value
-   double default_value; // Default plain value
+   double min_value;     // Minimum plain value. Must be finite (`std::isfinite` true)
+   double max_value;     // Maximum plain value. Must be finite
+   double default_value; // Default plain value. Must be in [min, max] range.
 } clap_param_info_t;
 
 typedef struct clap_plugin_params {