docs(output): warning_line module doc claims GitHub Actions ::warning:: recognition out of the box; wrong syntax + needs problem matcher

[dekobon]

Summary

The warning_line module doc claims its Clang/GCC and MSVC warning
lines are recognized by "GitHub Actions ::warning::" annotators "out
of the box", but neither writer emits the ::warning:: workflow-command
syntax, and GitHub Actions does not auto-recognize Clang/MSVC lines
without a registered problem matcher.

Location

• src/output/warning_line.rs:5-11 (module doc)

Evidence

//! Editor- and CI-annotator-friendly inline warnings: one offender per
//! line, in the conventional Clang/GCC and MSVC formats that quickfix
//! parsers (VS Code, IntelliJ, Vim) and CI annotators (GitHub Actions
//! `::warning::`, GitLab, Jenkins warnings-ng) recognize out of the
//! box.

Two inaccuracies:

1. Wrong syntax token. ::warning:: (more precisely
   ::warning file=...,line=...::message) is GitHub Actions'
   workflow-command syntax. These writers emit Clang
   (path:line:col: warning: msg [rule]) and MSVC
   (path(line,col): warning : msg) lines — a completely different
   format. The native ::warning file=...:: annotations are produced
   elsewhere (the CLI annotation path in
   big-code-analysis-cli/src/check_format.rs, which percent-encodes
   file= properties), not here.

2. "out of the box" overstates recognition. GitHub Actions does not
   parse Clang/GCC or MSVC diagnostic lines automatically; it requires a
   registered problem matcher. The sibling doc in the CLI gets this
   right:

   //! - [`AggregatedFormat::ClangWarning`] — clang/GCC warning lines
   //!   (editor quickfix parsers, GitHub Actions problem matchers).
   

   (big-code-analysis-cli/src/check_format.rs:17-18)

Expected Behavior

The module doc should either drop the ::warning:: reference (since
these writers do not emit that format) or rephrase to "GitHub Actions
problem matchers" to match the CLI doc, and avoid implying the lines are
auto-recognized without a matcher.

Actual Behavior

The doc conflates the Clang/MSVC line formats with GitHub Actions'
native ::warning:: workflow-command syntax and claims out-of-the-box
recognition that requires a problem matcher.

Impact

Reader-facing API documentation (this is a published-crate module whose
writers are re-exported from lib.rs). A user wiring write_clang_warning
into a GitHub Actions workflow expecting annotations to "just appear"
will see plain log text and no annotations until they register a problem
matcher. No runtime behavior is affected.

---

Resolution

Fixed in 7a41184: warning_line.rs module doc no longer claims GH Actions ::warning:: or "out of the box" CI recognition; problem matcher requirement documented.

[dekobon]

General Plan for Fix

Root Cause

The module doc was written describing the intent (CI-annotator-friendly
output) and reached for "GitHub Actions ::warning::" as a recognizable
example, but ::warning:: is the workflow-command syntax these writers
do not emit. The sibling CLI doc (check_format.rs:17-18) already states
the accurate "GitHub Actions problem matchers" framing; the library
module doc drifted from it.

Implementation Steps

1. Edit the module doc in src/output/warning_line.rs (lines 8-11):
   replace "CI annotators (GitHub Actions ::warning::, GitLab, Jenkins
   warnings-ng) recognize out of the box" with wording that (a) drops the
   ::warning:: token and (b) names "GitHub Actions problem matchers"
   (and, if kept, GitLab / Jenkins warnings-ng matchers), removing the
   "out of the box" claim or qualifying it as "with a registered problem
   matcher". Mirror the CLI doc phrasing for consistency.
2. No code change; the writers themselves are correct.

Tests to Add/Update

• None required (doc-only). The existing format snapshot tests
  (clang_*, msvc_*) already pin the emitted line shape and confirm
  these are not ::warning:: syntax.

Verification

• cargo doc --no-deps -p big-code-analysis builds with
  RUSTDOCFLAGS="-D warnings".
• Manual verification: rendered rustdoc for the module no longer
  mentions ::warning:: or "out of the box"; it matches the CLI's
  "problem matchers" framing.

[dekobon]

Fixed in 7a41184. The warning_line.rs module doc made two false claims: (1) attributed GitHub Actions ::warning:: workflow-command syntax to these writers — that syntax is produced elsewhere, on the CLI annotation path (check_format.rs); these writers emit plain Clang/GCC and MSVC warning lines; (2) claimed CI annotators recognize those formats "out of the box" — they do not without a registered problem matcher. Rewrote the module doc to match the accurate CLI sibling doc: editor quickfix parsers recognize the formats natively, CI needs a problem matcher.

[dekobon]

Fixed and merged to main in #957. GitHub did not auto-close this from the batched commit's single Fixes #a #b #c … trailer (only the first referenced issue auto-closes); closing manually. See the Resolution section in the body for details.