undo: doc

Author: abique

include/clap/ext/draft/undo.h

@@ -63,8 +63,8 @@ typedef struct clap_undo_delta_properties {
    uint32_t format_version;
 } clap_undo_delta_properties_t;
 
-// Use CLAP_EXT_UNDO_DELTA
-// This is an optional interface, using deltas is an optimization versus making state snapshot.
+// Use CLAP_EXT_UNDO_DELTA.
+// This is an optional interface, using deltas is an optimization versus making a state snapshot.
 typedef struct clap_plugin_undo_delta {
    // Asks the plugin the delta properties.
    // [main-thread]
@@ -96,12 +96,11 @@ typedef struct clap_plugin_undo_delta {
                         size_t               delta_size);
 } clap_plugin_undo_delta_t;
 
-// Use CLAP_EXT_UNDO_CONTEXT
+// Use CLAP_EXT_UNDO_CONTEXT.
 // This is an optional interface, that the plugin can implement in order to know about
 // the current undo context.
 typedef struct clap_plugin_undo_context {
-   // Indicate if it is currently possible to perform a redo or undo operation.
-   // if can_* is false then it invalidates the corresponding name.
+   // Indicate if it is currently possible to perform an undo or redo operation.
    // [main-thread & plugin-subscribed-to-undo-context]
    void(CLAP_ABI *set_can_undo)(const clap_plugin_t *plugin, bool can_undo);
    void(CLAP_ABI *set_can_redo)(const clap_plugin_t *plugin, bool can_redo);
@@ -113,7 +112,7 @@ typedef struct clap_plugin_undo_context {
    void(CLAP_ABI *set_redo_name)(const clap_plugin_t *plugin, const char *name);
 } clap_plugin_undo_context_t;
 
-// Use CLAP_EXT_UNDO
+// Use CLAP_EXT_UNDO.
 typedef struct clap_host_undo {
    // Begins a long running change.
    // The plugin must not call this twice: there must be either a call to cancel_change() or
@@ -165,7 +164,10 @@ typedef struct clap_host_undo {
                                bool               delta_can_undo);
 
    // Asks the host to perform the next undo or redo step.
-   // This operation may be asynchronous and isn't available while the host is within a change.
+   //
+   // Note: this maybe a complex and asynchronous operation, which may complete after
+   // this function returns.
+   //
    // [main-thread]
    void(CLAP_ABI *undo)(const clap_host_t *host);
    void(CLAP_ABI *redo)(const clap_host_t *host);