spec: add parameter postfixes (#43)

* first draft:
- restricted limits to scalar numeric types
- consolidated explanation to avoid repetition

* change `_use`postfix to `_enable`

* - `_enable` postfix is now a boolean
- fixed typo in issue reference
- added entry in changelog

* Boolean fix

---------

Co-authored-by: Peter Braun <peter.braun@helmholtz-berlin.de>

Author: Bilchreis

issues/077 predefined parameter name prefixes.rst

@@ -33,8 +33,8 @@ prefixed parameters which are used instead of changeable parameter properties.
 
 :note: In the below listing, ``<paramname>`` is a placeholder for the name of the relevant parameter.
 
-``use_<paramname>``
-  an Enum (1:On, 0:Off), allowing to enable or disable the effect of
+``<paramname>_enable``
+  an Enum (0:Off, 1:On), allowing to enable or disable the effect of
   ``<paramname>`` where applicable.
 
 ``limit_<paramname>``
@@ -67,7 +67,14 @@ Possible candidates:
 * keep 'target_limits' (with 's' at end in contrast to '_limit')
 * 'target_max' / 'target_min' in case of single limits
 
-No decision on the actual values yet.
+Decisions made in 2023-02-14_vidconf:
+
+* postfix notation is preferred
+* '_enable' is used instead of '_use'/'_used'/'_enabled' to en-/disable functionalities
+* '_limits' is removed in favor of '_min' and '_max'
+
+Note: In 2023-09-26_vidconf it was suggested that '_on' might be superior to '_enable',
+but no formal decision was recorded. The current specification uses '_enable'.
 
 In 2023-09-26_vidconf it was proposed to include ``<paramname>_check`` as a registed postfix
 for checking the validity of parameter ``<paramname>``.

protocol/specification/accessibles.rst

@@ -362,19 +362,53 @@ Coupled modules
     parameter with the name of the controlling module).
 
 
-Limits and offset
-~~~~~~~~~~~~~~~~~
-
-.. parameter:: target_limits
-
-    In addition to the range given in the `datainfo` property of the
-    `target` parameter, a SEC node might offer changeable limits restricting
-    the allowed range even more.  `target_limits` is structured as a
-    :ref:`tuple <tuple>` with two numeric members indicating the lower and upper end of
-    a valid interval for the setting of the `target` parameter.  The
-    `datainfo` property of the `target` parameter must match the members of
-    the `datainfo` property of `target_limits`.  The SEC node must reply
-    with an error in case a given target value does not fit into the interval.
+Parameter postfixes
+~~~~~~~~~~~~~~~~~~~
+
+In addition to the static ``"min"`` and ``"max"`` data properties given in the `datainfo` property of a parameter, a SEC
+node might offer dynamic limits restricting the allowed range even more.
+These limits can be specified in two mutually exclusive ways, either by
+individual ``<parameter_name>_min`` and/or ``<parameter_name>_max`` parameters, 
+or by a single ``<parameter_name>_limits`` parameter.
+
+.. note:: These dynamic limits are only allowed for parameters with scalar numeric datatypes.
+
+.. parameter:: <parameter_name>_min
+
+    An individual minimum value (of the same type as ``<parameter_name>``)
+    specifying the dynamic accepted minimum of a parameter. The SEC node must reply with
+    an error in case a given parameter value is below this minimum.
+
+.. parameter:: <parameter_name>_max
+
+    An individual maximum value (of the same type as ``<parameter_name>``)
+    specifying the dynamic accepted maximum of a parameter. The SEC node must reply with
+    an error in case a given parameter value is above this maximum.
+
+.. parameter:: <parameter_name>_limits
+
+    A :ref:`tuple <tuple>` with two numeric members indicating the lower and
+    upper end of a valid interval.  The `datainfo` property of
+    ``<parameter_name>`` must match the members of the `datainfo` property of
+    ``<parameter_name>_limits``.  The SEC node must reply with an error in case
+    a given parameter value does not fit into the interval.
+
+    .. note:: ``<parameter_name>_limits`` and the pair ``<parameter_name>_min`` /
+              ``<parameter_name>_max`` are mutually exclusive and may not coexist at the same
+              time on the same module.
+
+.. parameter:: <parameter_name>_enable
+
+    A boolean, allowing to enable or disable the effect of ``<parameter_name>`` where applicable.
+
+.. dropdown:: Related issues
+
+    | :issue:`073 HasLimits and HasOffset` 
+    | :issue:`077 predefined parameter name prefixes` 
+
+
+Feature related parameters
+~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 .. _offset:
 

protocol/specification/changes.rst

@@ -57,6 +57,10 @@ loss of functionality.
 
 - Optional SECoP transport over WebSockets has been specified (:ref:`rfc-107`).
 
+- Predefined parameter postfixes have been specified to allow enabling/disabling
+  parameters and specifying dynamic limits (:issue:`077 predefined parameter name prefixes`). 
+  The previously explicitly defined `target_limits` parameter follows this `_limits` postfix pattern. 
+
 
 Version 1.1
 -----------