Use non-normative should in Javadocs (#8390)

Author: trask

api/all/src/main/java/io/opentelemetry/api/common/AttributesBuilder.java

@@ -44,7 +44,7 @@ public interface AttributesBuilder {
    * <p>Simple attributes ({@link AttributeType#STRING}, {@link AttributeType#LONG}, {@link
    * AttributeType#DOUBLE}, {@link AttributeType#BOOLEAN}, {@link AttributeType#STRING_ARRAY},
    * {@link AttributeType#LONG_ARRAY}, {@link AttributeType#DOUBLE_ARRAY}, {@link
-   * AttributeType#BOOLEAN_ARRAY}) SHOULD be used whenever possible. Instrumentations SHOULD assume
+   * AttributeType#BOOLEAN_ARRAY}) should be used whenever possible. Instrumentations should assume
    * that backends do not index individual properties of complex attributes, that querying or
    * aggregating on such properties is inefficient and complicated, and that reporting complex
    * attributes carries higher performance overhead.

api/incubator/src/main/java/io/opentelemetry/api/incubator/common/ExtendedAttributeKey.java

@@ -114,8 +114,8 @@ static ExtendedAttributeKey<ExtendedAttributes> extendedAttributesKey(String key
    * <p>Simple attributes ({@link ExtendedAttributeType#STRING}, {@link ExtendedAttributeType#LONG},
    * {@link ExtendedAttributeType#DOUBLE}, {@link ExtendedAttributeType#BOOLEAN}, {@link
    * ExtendedAttributeType#STRING_ARRAY}, {@link ExtendedAttributeType#LONG_ARRAY}, {@link
-   * ExtendedAttributeType#DOUBLE_ARRAY}, {@link ExtendedAttributeType#BOOLEAN_ARRAY}) SHOULD be
-   * used whenever possible. Instrumentations SHOULD assume that backends do not index individual
+   * ExtendedAttributeType#DOUBLE_ARRAY}, {@link ExtendedAttributeType#BOOLEAN_ARRAY}) should be
+   * used whenever possible. Instrumentations should assume that backends do not index individual
    * properties of complex attributes, that querying or aggregating on such properties is
    * inefficient and complicated, and that reporting complex attributes carries higher performance
    * overhead.

api/incubator/src/main/java/io/opentelemetry/api/incubator/common/ExtendedAttributesBuilder.java

@@ -38,8 +38,8 @@ default <T> ExtendedAttributesBuilder put(AttributeKey<T> key, T value) {
    * <p>Simple attributes ({@link ExtendedAttributeType#STRING}, {@link ExtendedAttributeType#LONG},
    * {@link ExtendedAttributeType#DOUBLE}, {@link ExtendedAttributeType#BOOLEAN}, {@link
    * ExtendedAttributeType#STRING_ARRAY}, {@link ExtendedAttributeType#LONG_ARRAY}, {@link
-   * ExtendedAttributeType#DOUBLE_ARRAY}, {@link ExtendedAttributeType#BOOLEAN_ARRAY}) SHOULD be
-   * used whenever possible. Instrumentations SHOULD assume that backends do not index individual
+   * ExtendedAttributeType#DOUBLE_ARRAY}, {@link ExtendedAttributeType#BOOLEAN_ARRAY}) should be
+   * used whenever possible. Instrumentations should assume that backends do not index individual
    * properties of complex attributes, that querying or aggregating on such properties is
    * inefficient and complicated, and that reporting complex attributes carries higher performance
    * overhead.

context/src/main/java/io/opentelemetry/context/Context.java

@@ -212,7 +212,7 @@ default Context with(ImplicitContextKeyed value) {
    * Scope#close()} automatically.
    *
    * <p>The default implementation of this method will store the {@link Context} in a {@link
-   * ThreadLocal}. Kotlin coroutine users SHOULD NOT use this method as the {@link ThreadLocal} will
+   * ThreadLocal}. Kotlin coroutine users should not use this method as the {@link ThreadLocal} will
    * not be properly synced across coroutine suspension and resumption. Instead, use {@code
    * withContext(context.asContextElement())} provided by the {@code opentelemetry-extension-kotlin}
    * library.

context/src/main/java/io/opentelemetry/context/ImplicitContextKeyed.java

@@ -23,7 +23,7 @@ public interface ImplicitContextKeyed {
    * <p>This method is equivalent to {@code Context.current().with(value).makeCurrent()}.
    *
    * <p>The default implementation of this method will store the {@link ImplicitContextKeyed} in a
-   * {@link ThreadLocal}. Kotlin coroutine users SHOULD NOT use this method as the {@link
+   * {@link ThreadLocal}. Kotlin coroutine users should not use this method as the {@link
    * ThreadLocal} will not be properly synced across coroutine suspension and resumption. Instead,
    * use {@code withContext(value.asContextElement())} provided by the {@code
    * opentelemetry-extension-kotlin} library.

sdk/common/src/main/java/io/opentelemetry/sdk/resources/package-info.java

@@ -13,7 +13,7 @@
  *
  * <p>Attribute keys, and attribute values MUST contain only printable ASCII (codes between 32 and
  * 126, inclusive) and less than 256 characters. Type and attribute keys MUST have a length greater
- * than zero. They SHOULD start with a domain name and separate hierarchies with / characters, e.g.
+ * than zero. They should start with a domain name and separate hierarchies with / characters, e.g.
  * k8s.io/namespace/name.
  */
 @ParametersAreNonnullByDefault

sdk/metrics/src/main/java/io/opentelemetry/sdk/metrics/export/MetricProducer.java

@@ -19,7 +19,7 @@
  * <p>Alternative {@link MetricProducer} implementations can be used to bridge aggregated metrics
  * from other frameworks, and are registered with {@link
  * SdkMeterProviderBuilder#registerMetricProducer(MetricProducer)}. NOTE: When possible, metrics
- * from other frameworks SHOULD be bridged using the metric API, normally with asynchronous
+ * from other frameworks should be bridged using the metric API, normally with asynchronous
  * instruments which observe the aggregated state of the other framework. However, {@link
  * MetricProducer} exists to accommodate scenarios where the metric API is insufficient. It should
  * be used with caution as it requires the bridge to take a dependency on {@code

sdk/metrics/src/main/java/io/opentelemetry/sdk/metrics/internal/view/FilteredAttributes.java

@@ -47,7 +47,7 @@ private FilteredAttributes(Object[] sourceData, int hashcode, int size) {
   /**
    * Create a {@link FilteredAttributes} instance.
    *
-   * @param source the source attributes, which SHOULD be based on the standard {@link
+   * @param source the source attributes, which should be based on the standard {@link
    *     ImmutableKeyValuePairs}. If not, the source will first be converted to the standard
    *     implementation.
    * @param includedKeys the set of attribute keys to include in the output.

sdk/profiles/src/main/java/io/opentelemetry/sdk/profiles/data/ProfileData.java

@@ -121,7 +121,7 @@ default byte[] getProfileIdBytes() {
   /**
    * Returns the original payload, in a profiler-native format e.g. JFR. Optional. Default behavior
    * should be to not include the original payload. If the original payload is in pprof format, it
-   * SHOULD not be included in this field.
+   * should not be included in this field.
    */
   ByteBuffer getOriginalPayload();