Weaver code generation breaks HTML links.

[marcalff]

This is an example of generated code (in opentelemetry-cpp):

/**
 * Time disk spent activated
 * <p>
 * The real elapsed time ("wall clock") used in the I/O path (time from operations running in
 * parallel are not counted). Measured as: <ul> <li>Linux: Field 13 from <a
 * href="https://www.kernel.org/doc/Documentation/ABI/testing/procfs-diskstats">procfs-diskstats</a></li>
 *   <li>Windows: The complement of
 * <a
 * href="https://learn.microsoft.com/archive/blogs/askcore/windows-performance-monitor-disk-counters-explained#windows-performance-monitor-disk-counters-explained">"Disk%
 * Idle Time"</a> performance counter: @code uptime * (100 - "Disk\% Idle Time") / 100 @endcode</li>
 * </ul>
 * <p>
 * counter
 */

This causes at build time (when using -Wdocumentation):

In file included from /home/runner/work/opentelemetry-cpp/opentelemetry-cpp/examples/common/metrics_foo_library/foo_library.cc:26:
/home/runner/work/opentelemetry-cpp/opentelemetry-cpp/api/include/opentelemetry/semconv/incubating/system_metrics.h:279:2: error: HTML start tag prematurely ended, expected attribute name or '>' [-Werror,-Wdocumentation]
  279 |  * href="https://www.kernel.org/doc/Documentation/ABI/testing/procfs-diskstats">procfs-diskstats</a></li>
      |  ^
/home/runner/work/opentelemetry-cpp/opentelemetry-cpp/api/include/opentelemetry/semconv/incubating/system_metrics.h:278:75: note: HTML tag started here
  278 |  * parallel are not counted). Measured as: <ul> <li>Linux: Field 13 from <a
      |                                                                           ^

The problem here is that when a link is generated in some text, as in:

text before <a href="https://www.kernel.org/doc/Documentation/ABI/testing/procfs-diskstats">procfs-diskstats</a> text after

when the text is later reformatted and added in a comment section (using *), the html link is broken.

[marcalff]

Suggestion:

Instead of commenting like this:

/**
 * line 1
 * line 2
 * line 3
 */

it will be much simpler to use:

/**
 line 1
 line 2
 line 3
 */

which will not alter the content, in case of embedded html markup.

[jsuereth]

@marcalff sorry for late response here.

We use the *-per-line comment format to support Java, and common javadoc lints here.

I agree this is a bug. Previously I had created some new word wrapping algorithms to support not splitting over lines appropriately, however this was highly customized.

Can you share the full configuration you're giving the comment formatter so I can check whether or not you're in a supported path for that customization? That'll help me either guide you to working config and/or fix the path you're on for word-wrapping so it doesn't needlessly break links.

[marcalff]

Hi @jsuereth

opentelemetry-cpp uses this weaver.yaml file:

https://github.com/open-telemetry/opentelemetry-cpp/blob/main/buildscripts/semantic-convention/templates/registry/weaver.yaml

Initially, it read as:

comment_formats:
  cpp:
    format: html
    header: "/**"
    prefix: "  * " <======================= HERE
    footer: " */"
    indent_type: Space
    trim: true
    remove_trailing_dots: false
    enforce_trailing_dots: false
    old_style_paragraph: true
    omit_closing_li: false
    inline_code_snippet: "@code {{code}} @endcode"
    block_code_snippet: "@verbatim {{code}} @endverbatim"
default_comment_format: cpp

After filing this report, I then remembered that the comment format could be configured, so I changed them to:

comment_formats:
  cpp:
    format: html
    header: "/**"
    prefix: "  " <======================= HERE
    footer: " */"
    ...

avoiding the issue entirely.

Code generation now works without a prefix.

What remains to clarify is whether having a prefix is viable (because damaging internal comments markup like http links is prevented in weaver), or if this path is too fragile to maintain, making the prefix option too error prone.

[marcalff]

The fix was implemented in:

• [SEMANTIC CONVENTIONS] Fix comment style to preserve markup opentelemetry-cpp#3444

[jsuereth]

The prefix option should be fully supported. I believe we can also fix the link issue.

Our current solution for word-wrapping things like this is to have two mechanisms for assigning content to lines -

• One which will fragment words (sometimes too naively)
• One which assigns a fragment as an "unbroken string" where we treat the whole block as a word.

See, e.g. https://github.com/open-telemetry/weaver/blob/main/crates/weaver_forge/src/formats/html.rs#L91

If you see our HTML rendering, you can see we only treat tags as unbroken lines: https://github.com/open-telemetry/weaver/blob/main/crates/weaver_forge/src/formats/html.rs#L351

We could provide an option to the comment filter to treat more things as unbreakable lines.

I still plan to put up a test and see if we can fix your original issue, but glad you have a workaround!