boostorg / boostorg/url

docs: 112 snippet tags are compiled but never included in any page

Open
#1,000 0 comments 0 reactions 0 assignees View on GitHub
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

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.