open-telemetry / open-telemetry/weaver

Weaver code generation breaks HTML links.

Open
#751 5 comments 0 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

bug template engine
Dominant language
Rust
Stars
486
Forks
108
Avg merge
3d 4h
Merged PRs (30d)
40

Description

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.

Contributor guide

Open the contributing guide

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

Research direction

Start by tracing Weaver's code-generation path that reformats text into comment sections, using the linked generated example as the reproduction case. Check how HTML links are handled when line wrapping adds comment prefixes. Done means generated links remain valid and the shown -Wdocumentation build no longer reports the HTML-tag error.

Written by the indexing model from the issue text.

Assessment

Tech stack
rust
Domain
documentation, tooling
Issue type
Bug
Difficulty
3/5
Estimated time
1-2 days
Activity status
Stale
Clarity
Mostly clear
Newbie friendliness
42/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.