open-telemetry / open-telemetry/weaver
Weaver code generation breaks HTML links.
Nobody has claimed this yet.
- 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
First steps
- Read the whole issue, then the project's contributing guide.
- Comment on the issue to say you are picking it up — it saves two people doing the same work.
- Fork the repository and make your change on a branch.
- 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