Documentation fixes for the Quick Look and Parsing pages

[alandefreitas]

Closes #996, #997, #998.

Three small, self-contained fixes to the docs reported by the same author.

#996 — u1.set_host(u2.host()) example doesn't compile

doc/modules/ROOT/pages/quicklook.adoc showed:

u1.set_host(u2.host());

with u1 introduced as a url_view in the surrounding prose. url_view is immutable, so the snippet doesn't compile. The example is a raw [source,cpp] block (not an include:: of a tested snippet), so the fix is to make the freestanding code self-contained:

url      u1 = parse_uri( "http://www.example.com" ).value();
url_view u2 = parse_uri( "http://other.example.com" ).value();
u1.set_host(u2.host());

u1 is now a url (mutable), which is what set_host requires.

#997 — encoded vs decoded segments produced the same output

In quicklook.adoc, the "encoded segments" section claimed the loop prints:

path
to
my-file.txt

But the tested snippet asserts:

BOOST_TEST(equal_range(segs_encoded, {"path", "to", "my%2dfile.txt"}));

i.e. the actual library output is my%2dfile.txt — the encoded form. The doc was showing the decoded string in the "encoded" block, making the two adjacent examples look identical. Updated the block to match what the snippet actually prints.

#998 — "parses a string literal" intro didn't show the parse

doc/modules/ROOT/pages/urls/parsing.adoc opened with:

The following example parses a string literal containing a URI: [code_urls_parsing_1]

code_urls_parsing_1 is only the string_view declaration — no parse_uri call. Further down the same page, the prose "The following two statements are equivalent:" was paired with code_urls_parsing_2, which is a single parse_uri call (not two statements at all). The blocks were transposed.

Reorganised so the intro shows both code_urls_parsing_1 (string) and code_urls_parsing_2 (parse_uri call) in one fenced block — making the "parses a string literal" wording accurate — and the "two equivalent statements" section now correctly pairs snippet_parsing_3 (r.value()) and snippet_parsing_4 (*r), which are the two equivalent ways to obtain the url_view from the result.

Verified the Antora build (doc/build_antora.sh) renders both blocks correctly.

Follow-up: orphan snippets

While verifying #998 I ran a tags-defined vs tags-included comparison and found 112 snippet tags compiled and tested but never included in any page. Largest clusters: snippet_parsing_path_* (22), snippet_parsing_authority_* (21), snippet_parsing_query_* (16), snippet_modifying_path_* (15). The kind of misalignment that produced #998 is structurally invisible today.

Filed as a separate issue with a proposed CI lint to prevent regressions. Not in this PR's scope.

[cppalliance-bot]

An automated preview of the documentation is available at https://999.url.prtest2.cppalliance.org/index.html

If more commits are pushed to the pull request, the docs will rebuild at the same URL.

2026-05-13 22:32:27 UTC

[cppalliance-bot]

GCOVR code coverage report https://999.url.prtest2.cppalliance.org/gcovr/index.html
LCOV code coverage report https://999.url.prtest2.cppalliance.org/genhtml/index.html
Coverage Diff Report https://999.url.prtest2.cppalliance.org/diff-report/index.html

Build time: 2026-05-13 22:45:27 UTC

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 99.12%. Comparing base (9d65427) to head (65afa4a).

Additional details and impacted files

@@           Coverage Diff            @@
##           develop     #999   +/-   ##
========================================
  Coverage    99.12%   99.12%           
========================================
  Files          154      154           
  Lines        10093    10093           
========================================
  Hits         10005    10005           
  Misses          88       88           

---

Continue to review full report in Codecov by Sentry.

Legend - Click here to learn more
Δ = absolute <relative> (impact), ø = not affected, ? = missing data
Powered by Codecov. Last update 9d65427...65afa4a. Read the comment docs.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.