From aa670d1f007cc4d1963869ffaf26ce32ec7ed5e2 Mon Sep 17 00:00:00 2001
From: Alexandre Bique <bique.alexandre@gmail.com>
Date: Mon, 8 Jan 2024 09:17:35 +0100
Subject: [PATCH] Adjust state context's documentation

---
 include/clap/ext/state-context.h | 11 ++++++-----
 include/clap/ext/state.h         |  4 ++++
 2 files changed, 10 insertions(+), 5 deletions(-)

diff --git a/include/clap/ext/state-context.h b/include/clap/ext/state-context.h
index f1cf1eff..20248b37 100644
--- a/include/clap/ext/state-context.h
+++ b/include/clap/ext/state-context.h
@@ -21,10 +21,12 @@
 ///        clap_plugin_state_context.save(CLAP_STATE_CONTEXT_FOR_PRESET),
 ///        CLAP_STATE_CONTEXT_FOR_PRESET)
 ///
-/// If in doubt, choose CLAP_STATE_CONTEXT_FOR_PRESET as option.
-/// 
+/// If in doubt, fallback to clap_plugin_state.
+///
 /// If the plugin implements CLAP_EXT_STATE_CONTEXT then it is mandatory to also implement
 /// CLAP_EXT_STATE.
+///
+/// It is unspecified which context is equivalent to clap_plugin_state.{save,load}()
 
 #ifdef __cplusplus
 extern "C" {
@@ -33,15 +35,14 @@ extern "C" {
 static CLAP_CONSTEXPR const char CLAP_EXT_STATE_CONTEXT[] = "clap.state-context/2";
 
 enum clap_plugin_state_context_type {
-   // suitable for loading a state as a preset
+   // suitable for storing and loading a state as a preset
    CLAP_STATE_CONTEXT_FOR_PRESET = 1,
 
   // suitable for duplicating a plugin instance
    CLAP_STATE_CONTEXT_FOR_DUPLICATE = 2,
 
-   // suitable for loading a state during loading a project/song
+   // suitable for storing and loading a state within a project/song
    CLAP_STATE_CONTEXT_FOR_PROJECT = 3,
-
 };
 
 typedef struct clap_plugin_state_context {
diff --git a/include/clap/ext/state.h b/include/clap/ext/state.h
index 8d028e1b..b8b698c0 100644
--- a/include/clap/ext/state.h
+++ b/include/clap/ext/state.h
@@ -10,6 +10,10 @@
 /// values and non-parameter state. This is used to persist a plugin's state
 /// between project reloads, when duplicating and copying plugin instances, and
 /// for host-side preset management.
+///
+/// If you need to know if the save/load operation is meant for duplicating a plugin
+/// instance, for saving/loading a plugin preset or while saving/loading the project
+/// then have a look at clap_plugin_state_context_t.
 
 static CLAP_CONSTEXPR const char CLAP_EXT_STATE[] = "clap.state";