chore(semantic-conventions): bump weaver; use comment filter rather t…

…han deprecated comment_with_prefix (#5100)

scripts/semconv/generate.sh

@@ -7,7 +7,7 @@ ROOT_DIR="${SCRIPT_DIR}/../../"
 
 # freeze the spec version to make SpanAttributess generation reproducible
 SPEC_VERSION=v1.27.0
-GENERATOR_VERSION=0.8.0
+GENERATOR_VERSION=v0.10.0
 
 # When running on windows and your are getting references to ";C" (like Telemetry;C)
 # then this is an issue with the bash shell, so first run the following in your shell:

scripts/semconv/templates/registry/stable/docstring.ts.j2

@@ -1,21 +1,34 @@
-{% macro strong_reqs(string) -%}{{ string | replace(" MUST ", " **MUST** ") | replace(" MUST NOT ", " **MUST NOT** ") | replace(" SHOULD ", " **SHOULD** ") | replace(" SHOULD NOT ", " **SHOULD NOT** ") |  replace(" MAY ", " **MAY** ") | replace(" NOT ", " **NOT** ") }}{% endmacro -%}
+{% macro strong_rfc2119(string) -%}{{ string | regex_replace("\\b(MUST NOT|MUST|REQUIRED|SHALL NOT|SHALL|SHOULD NOT|SHOULD|RECOMMENDED|MAY|OPTIONAL)\\b", "**$1**") }}{% endmacro -%}
 
-{% macro docstring(obj, type="value") -%}/**
-{{ strong_reqs(obj.brief | comment_with_prefix(" * ")) }}
-{% if obj.examples is sequence %}{% for example in obj.examples %}
- *
- * @example {{ example }}
-{% endfor %}{%elif obj.examples%}
- *
- * @example {{ obj.examples | print_member_value }}
-{% endif %}{% if obj.note %}
- *
-{{ ("@note " ~ strong_reqs(obj.note)) | comment_with_prefix(" * ") }}
-{% endif %}{% if (obj.stability) != "stable" %}
- *
- * @experimental This {{type}} is experimental and is subject to breaking changes in minor releases of `@opentelemetry/semantic-conventions`.
-{% endif %}{% if obj.deprecated %}
- *
- * @deprecated {{ strong_reqs(obj.deprecated) | comment_with_prefix(" * ") }}
-{% endif %}
- */{% endmacro -%}
+{% macro docstring(obj, type="value") -%}
+{%- set examples_jsdoc %}
+  {% if obj.examples is sequence %}
+    {% for example in obj.examples %}
+@example {{ example }}
+    {% endfor %}
+  {% elif obj.examples %}
+@example {{ obj.examples | print_member_value }}
+  {% endif %}
+{% endset -%}
+
+{%- if obj.note %}
+  {% set note_jsdoc = "@note " ~ strong_rfc2119(obj.note) %}
+{% endif -%}
+
+{%- if obj.stability != "stable" %}
+  {% set stability_jsdoc = "@experimental This " ~ type ~ " is experimental and is subject to breaking changes in minor releases of `@opentelemetry/semantic-conventions`." %}
+{% endif -%}
+
+{%- if obj is deprecated %}
+  {%- set deprecated_jsdoc = "\n@deprecated " ~ strong_rfc2119(obj.deprecated) -%}
+{%- endif -%}
+
+{{ [
+  strong_rfc2119(obj.brief) | trim,
+  "\n",
+  examples_jsdoc,
+  note_jsdoc,
+  stability_jsdoc,
+  deprecated_jsdoc,
+] | comment }}
+{%- endmacro -%}

scripts/semconv/templates/registry/stable/weaver.yaml

@@ -1,6 +1,21 @@
+
 params:
   excluded_attributes: ["messaging.client_id"]
 
+# https://github.com/open-telemetry/weaver/blob/main/crates/weaver_forge/README.md#comment-filter
+comment_formats:
+  jsdoc:
+    format: markdown
+    header: '/**'
+    # Note: This results in trailing whitespace on empty lines. IMHO the
+    # 'comment' filter should handle those.
+    prefix: ' * '
+    footer: ' */'
+    trim: true
+    indent_first_level_list_items: true
+    escape_backslashes: true
+default_comment_format: jsdoc
+
 templates:
   - pattern: attributes.ts.j2
     # Remove file name prefix when per-pattern params are available https://github.com/open-telemetry/weaver/issues/288

semantic-conventions/CHANGELOG.md

@@ -15,6 +15,8 @@ All notable changes to the semantic-conventions package will be documented in th
 
 ### :house: (Internal)
 
+* chore: Minor improvements to formatting of comments. [#5100](https://github.com/open-telemetry/opentelemetry-js/pull/5100) @trentm
+
 ## 1.27.0
 
 * Version bump only