chore(semantic-conventions): bump weaver; use comment filter rather than deprecated comment_with_prefix

[trentm]

This slightly improves newlines (multiple @example jsdoc tags are cuddled
together) and some markdown formatting of content is improved (list item
bullets and indentation, reflow of blockquote). The current cost is
a trailing space on blank comment lines: ' * ', rather than ' *'.
I think the weaver 'comment' filter should handle this.

---

This is some prep work before looking at #5025 and update to semconv 1.28.0.

details on some changes to generated files with examples

• Improvement: remove spurious * comment prefix after @deprecated, e.g.:

@@ -1444,7 +1390,7 @@ export const ATTR_DB_CASSANDRA_SPECULATIVE_EXECUTION_COUNT = 'db.cassandra.specu
  *
  * @experimental This attribute is experimental and is subject to breaking changes in minor releases of `@opentelemetry/semantic-conventions`.
  *
- * @deprecated  * Replaced by `db.collection.name`.
+ * @deprecated Replaced by `db.collection.name`.
  */
 export const ATTR_DB_CASSANDRA_TABLE = 'db.cassandra.table' as const;

• Improvment: cuddle multiple @examples ... together. This is purely cosmetic for the source files, the tooltip (at least in VS Code) is the same with or without this cuddling. E.g.:

@@ -1657,7 +1602,6 @@ export const DB_COSMOSDB_OPERATION_TYPE_VALUE_UPSERT = "Upsert" as const;
  * RU consumed for that operation
  *
  * @example 46.18
- *
  * @example 1.0
  *
  * @experimental This attribute is experimental and is subject to breaking changes in minor releases of `@opentelemetry/semantic-conventions`.

• Debatable improvement: indented bullet lists in Markdown comments. E.g.:

@@ -2232,8 +2156,8 @@ export const ATTR_DEPLOYMENT_ENVIRONMENT = 'deployment.environment' as const;
  * This implies that resources carrying the following attribute combinations **MUST** be
  * considered to be identifying the same service:
  *
- * * `service.name=frontend`, `deployment.environment.name=production`
- * * `service.name=frontend`, `deployment.environment.name=staging`.
+ *   - `service.name=frontend`, `deployment.environment.name=production`
+ *   - `service.name=frontend`, `deployment.environment.name=staging`.

• Improvement: better reflow of multi-line blockquotes. E.g.:

@@ -3685,9 +3562,9 @@ export const ATTR_K8S_CLUSTER_NAME = 'k8s.cluster.name' as const;
  * Which states:
  *
  * > If generated according to one of the mechanisms defined in Rec.
- *   ITU-T X.667 | ISO/IEC 9834-8, a UUID is either guaranteed to be
- *   different from all other UUIDs generated before 3603 A.D., or is
- *   extremely likely to be different (depending on the mechanism chosen).
+ * > ITU-T X.667 | ISO/IEC 9834-8, a UUID is either guaranteed to be
+ * > different from all other UUIDs generated before 3603 A.D., or is
+ * > extremely likely to be different (depending on the mechanism chosen).

• Improvement: fix a spurious blank line in comment for many METRIC_ consts. E.g.:

@@ -916,22 +912,16 @@ export const METRIC_SYSTEM_DISK_MERGED = 'system.disk.merged' as const;
 export const METRIC_SYSTEM_DISK_OPERATION_TIME = 'system.disk.operation_time' as const;

 /**
-
- *
  * @experimental This metric is experimental and is subject to breaking changes in minor releases of `@opentelemetry/semantic-conventions`.
  */
 export const METRIC_SYSTEM_DISK_OPERATIONS = 'system.disk.operations' as const;

• Improvement: The emphasis on SHOULD et al RFC 2119 words (by strong_reqs in "dockstring.ts.j2") has been slightly improved using the replace_regex weaver filter. Also the "RECOMMENDED" RFC 2119 word was added to the list. E.g.:

@@ -1460,9 +1460,9 @@ export const DB_CLIENT_CONNECTIONS_STATE_VALUE_USED = "used" as const;
  * @example public.users
  * @example customers
  *
- * @note It is RECOMMENDED to capture the value as provided by the application without attempting to do any case normalization.
+ * @note It is **RECOMMENDED** to capture the value as provided by the application without attempting to do any case normalization.
  * If the collection name is parsed from the query text, it **SHOULD** be the first collection name found in the query and it **SHOULD** match the value provided in the query text including any schema and database name prefix.

• Negative: Using the weaver comment filter (https://github.com/open-telemetry/weaver/blob/main/crates/weaver_forge/README.md#comment-filter) and prefix: ' * ' results in a trailing space on empty comment lines. (I think this is weaver bug, or feature request.) E.g.:

 /**
  * The JSON-serialized value of each item in the `AttributeDefinitions` request field.
- *
+ * 
  * @example { "AttributeName": "string", "AttributeType": "string" }

[codecov]

Codecov Report

All modified and coverable lines are covered by tests ✅

Project coverage is 93.17%. Comparing base (87bd98e) to head (bf00f2a).
Report is 1 commits behind head on main.

Additional details and impacted files

@@            Coverage Diff             @@
##             main    #5100      +/-   ##
==========================================
- Coverage   93.18%   93.17%   -0.02%     
==========================================
  Files         315      315              
  Lines        8086     8086              
  Branches     1617     1617              
==========================================
- Hits         7535     7534       -1     
- Misses        551      552       +1     

see 1 file with indirect coverage changes

[JamieDanielson]

Improvment: cuddle multiple @examples ... together.

There's a chance this was intentional to ensure examples showed as two separate examples in the file, can we revisit?

[trentm]

TODOne(trent):

• follow up on @example rendering: not an issue
• follow up on the emphasis issue when it is the first word: fixed in commit 2babf73

[trentm]

• follow up on @example rendering

From Dan on OTel JS SIG: "realtime follow-up: blank line between examples doesn’t do anything" I.e. all good as is.

[trentm]

The last commit fixes the issue with not marking up "SHOULD" et al words if they are the start of a text section.

[trentm]

@dyladan Ready for your blessing/cursing now.

[dyladan]

Looks good to me. I assume https://github.com/open-telemetry/semantic-conventions/releases/tag/v1.28.0 is next?

[dyladan]

I support the strong_rfc2119 renaming. More clear what's actually going on.

[trentm]

I assume https://github.com/open-telemetry/semantic-conventions/releases/tag/v1.28.0 is next?

Yes.

I had been considering doing something for #5025 as well, possibly before a v1.28.0 tag release. I'll try to get to those today.