Normatively define synchronous instrument record/add parameters (open…

…-telemetry#3082)

* Normatively define sync inst record params

Communicate the parameters for the instrument record/add APIs using
normative key words adopted by this specification and defined in BCP-14.

* Apply suggestions from code review

Co-authored-by: jack-berg <[email protected]>
Co-authored-by: Robert Pająk <[email protected]>

* Update specification/metrics/api.md

Co-authored-by: Robert Pająk <[email protected]>

* Address feedback, all params required

Feedback to these changes pointed out the original intent of the
optional parameters is not to communicate the option for APIs, but for
users to provide the values. Update the changes to match this intent.

* This instead of the

Consistently use the same API identifier.

* Recommend no validation instead of requiring it

---------

Co-authored-by: jack-berg <[email protected]>
Co-authored-by: Robert Pająk <[email protected]>

specification/metrics/api.md

@@ -484,10 +484,25 @@ Increment the Counter by a fixed amount.
 This API SHOULD NOT return a value (it MAY return a dummy value if required by
 certain programming languages or systems, for example `null`, `undefined`).
 
-Required parameters:
+This API MUST accept the following parameter:
 
-* Optional [attributes](../common/README.md#attribute).
-* The increment amount, which MUST be a non-negative numeric value.
+* A numeric increment value.
+
+  The increment value needs to be provided by a user. If possible, this API
+  SHOULD be structured so a user is obligated to provide this parameter. If it
+  is not possible to structurally enforce this obligation, this API MUST be
+  documented in a way to communicate to users that this parameter is needed.
+
+  The increment value is expected to be non-negative. This API SHOULD be
+  documented in a way to communicate to users that this value is expected to be
+  non-negative. This API SHOULD NOT validate this value, that is left to
+  implementations of the API.
+* [Attributes](../common/README.md#attribute) to associate with the increment
+  value.
+
+  Users can provide attributes to associate with the increment value, but it is
+  up to their discretion. Therefore, this API MUST be structured to accept a
+  variable number of attributes, including none.
 
 The [OpenTelemetry API](../overview.md#api) authors MAY decide to allow flexible
 [attributes](../common/README.md#attribute) to be passed in as arguments. If
@@ -705,10 +720,24 @@ Updates the statistics with the specified amount.
 This API SHOULD NOT return a value (it MAY return a dummy value if required by
 certain programming languages or systems, for example `null`, `undefined`).
 
-Parameters:
+This API MUST accept the following parameter:
 
-* The numeric value to record, which MUST be a non-negative numeric value.
-* Optional [attributes](../common/README.md#attribute).
+* A numeric value to record.
+
+  The value needs to be provided by a user. If possible, this API SHOULD be
+  structured so a user is obligated to provide this parameter. If it is not
+  possible to structurally enforce this obligation, this API MUST be documented
+  in a way to communicate to users that this parameter is needed.
+
+  The value is expected to be non-negative. This API SHOULD be documented in a
+  way to communicate to users that this value is expected to be non-negative.
+  This API SHOULD NOT validate this value, that is left to implementations of
+  the API.
+* [Attributes](../common/README.md#attribute) to associate with the value.
+
+  Users can provide attributes to associate with the value, but it is up to
+  their discretion. Therefore, this API MUST be structured to accept a variable
+  number of attributes, including none.
 
 [OpenTelemetry API](../overview.md#api) authors MAY decide to allow flexible
 [attributes](../common/README.md#attribute) to be passed in as individual
@@ -939,10 +968,19 @@ Increment or decrement the UpDownCounter by a fixed amount.
 This API SHOULD NOT return a value (it MAY return a dummy value if required by
 certain programming languages or systems, for example `null`, `undefined`).
 
-Parameters:
+This API MUST accept the following parameter:
+
+* A numeric value to add.
 
-* The amount to be added, can be positive, negative or zero.
-* Optional [attributes](../common/README.md#attribute).
+  The value needs to be provided by a user. If possible, this API SHOULD be
+  structured so a user is obligated to provide this parameter. If it is not
+  possible to structurally enforce this obligation, this API MUST be documented
+  in a way to communicate to users that this parameter is needed.
+* [Attributes](../common/README.md#attribute) to associate with the value.
+
+  Users can provide attributes to associate with the value, but it is up to
+  their discretion. Therefore, this API MUST be structured to accept a variable
+  number of attributes, including none.
 
 [OpenTelemetry API](../overview.md#api) authors MAY decide to allow flexible
 [attributes](../common/README.md#attribute) to be passed in as individual