docs: 112 snippet tags are compiled but never included in any page
- Dominant language
- C++
- Stars
- 205
- Forks
- 60
- PR merge metrics
- No merged PRs in 30d
Description
`doc/modules/ROOT/examples/unit/snippets.cpp` defines tags via `// tag::NAME[]` / `// end::NAME[]` so they can be included in AsciiDoc pages with `include::example$unit/snippets.cpp[tag=NAME,indent=0]`. The snippets are also compiled and run as part of the unit-test suite, so they exercise the library and stay in sync with the API.
Today, **112 tags are defined and tested but never referenced by any documentation page**. They are pure dead weight: they contribute to compile time and test execution but no reader ever sees them.
## How to reproduce
From the repo root:
```sh
comm -23 \
<(grep -hoE '// tag::[A-Za-z_0-9]+\[\]' doc/modules/ROOT/examples/unit/snippets.cpp \
| sed 's|// tag::||; s|\[\]||' | sort -u) \
<(grep -rhoE 'tag=[A-Za-z_0-9]+' doc/modules/ROOT/pages/ \
| sed 's|tag=||' | sort -u)
```
## Findings
Counts grouped by prefix:
| count | prefix |
|------:|---------------------------------|
| 22 | `snippet_parsing_path_*` |
| 21 | `snippet_parsing_authority_*` |
| 16 | `snippet_parsing_query_*` |
| 15 | `snippet_modifying_path_*` |
| 7 | `snippet_parsing_fragment_*` |
| 5 | `snippet_parsing_url_*` |
| 5 | `snippet_components_2*` |
| 4 | `snippet_parse_*` |
| 4 | `snippet_modifying_[1-4]` |
| 2 | `snippet_parsing_scheme_*` |
| 2 | `snippet_headers_*` |
| 2 | `snippet_customization_*` |
| 2 | `snippet_compound_elements_0*` |
| 2 | `snippet_accessing_3*` |
| 1 | `snippet_using_static_pool_1` |
| 1 | `snippet_decoding_2` |
| 1 | `code_charset_1` |
The largest clusters look like material for dedicated "Parsing the path / authority / query / fragment" and "Modifying the path" tutorial sections that were either removed or never written. The compiled snippets are now orphans.
## Motivation
This is the structural cause of #998. The doc page said "The following example parses a string literal containing a URI" but the included snippet (`code_urls_parsing_1`) is only the `string_view` declaration; the actual `parse_uri` call is in `code_urls_parsing_2`, which was misused in a different section that claimed to show "two equivalent statements". The transposition went unnoticed because:
1. There is no build-time check that page prose matches snippet content.
2. There is no build-time check that defined tags are ever consumed.
Even fixing #998 by hand leaves the underlying invisibility: any future rename, refactor, or rewrite can transpose another pair the same way.
## Proposed fix
Two independent steps:
- Resolve the existing orphans
- Add a CI lint
Contributor guide
No contributing guide indexed for this repository
Research direction
Start with doc/modules/ROOT/examples/unit/snippets.cpp and the pages under doc/modules/ROOT/pages/, then run the comm/grep command from the issue to reproduce the orphan list. Trace the unused tag groups against existing or missing documentation sections and review the related #998 transposition. Done means the orphaned snippets are resolved and a CI lint checks that defined tags are consumed.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- cpp
- Domain
- ci-cd, documentation
- Issue type
- Feature
- Difficulty
- 4/5
- Estimated time
- 3-5 days
- Activity status
- Quiet
- Clarity
- Mostly clear
- Newbie friendliness
- 48/100