Add rant about bogus URI keys.

1 files changed, 15 insertions, 10 deletions

diff --git a/lv2/ns/ext/state/state.h b/lv2/ns/ext/state/state.h
index d4e4f5b..b450b93 100644
--- a/lv2/ns/ext/state/state.h
+++ b/lv2/ns/ext/state/state.h
@@ -99,16 +99,21 @@ typedef enum {
    @param flags LV2_State_Flags for @c value.
    @return 0 on success, otherwise a non-zero error code.
 
-   The host passes a callback of this type to LV2_State_Interface.save(). This callback
-   is called repeatedly by the plugin within LV2_State_Interface.save() to store all
-   the statements that describe its current state.
-
-   The host MAY fail to store a property if the type is not understood and is
-   not LV2_STATE_IS_POD and/or LV2_STATE_IS_PORTABLE. Implementations are
-   encouraged to use POD and portable values (e.g. string literals) wherever
-   possible, and use common types (e.g. types from
-   http://lv2plug.in/ns/ext/atom) regardless, since hosts are likely to already
-   contain the necessary implementation.
+   The host passes a callback of this type to LV2_State_Interface.save(). This
+   callback is called repeatedly by the plugin within
+   LV2_State_Interface.save() to store all the statements that describe its
+   current state.
+
+   DO NOT INVENT NONSENSE URI SCHEMES FOR THE KEY.  Best is to use keys from
+   existing vocabularies.  If nothing appropriate is available, use http URIs
+   that point to somewhere you can host documents, so you can make
+   documentation resolvable.  If this is not possible, invent a URN scheme,
+   e.g. urn:myproj:whatever.  The plugin MUST NOT pass an invalid URI key.
+
+   The host MAY fail to store a property for whatever reason, but SHOULD
+   store any property that is LV2_STATE_IS_POD and LV2_STATE_IS_PORTABLE.
+   Implementations SHOULD use the types from the LV2 Atom extension
+   (http://lv2plug.in/ns/ext/atom) wherever possible.
 
    Note that @c size MUST be > 0, and @c value MUST point to a valid region of
    memory @c size bytes long (this is required to make restore unambiguous).