From 6b9378537a9ca951d9d3901d4172fb8abbe26baa Mon Sep 17 00:00:00 2001
From: Michael Vandeberg <mvandeberg@users.noreply.github.com>
Date: Wed, 21 Oct 2026 09:07:07 -0600
Subject: [PATCH] docs: link @see targets with @ref and gate bare @see names

MrDocs treats the text after @see as an ordinary paragraph and does not
auto-link names in it, so every "See Also" entry written as `@see delay`
rendered as plain text. warn-broken-ref only checks @ref targets, so
nothing reported it. Rewrite the 122 bare @see lines in the public
headers as `@see @ref name`, moving prose out of the @see lines into the
description, and qualify tcp_server inside tcp_server::worker_base, which
resolved to the constructor. Drop socket_option's @see of
native_socket_option: MrDocs does not extract that namespace, so no link
to it can resolve, and the description already names it.

Port capy's style guide rule B6 and its doc-lint.mjs check, which flags
any @see paragraph, including wrapped lines, holding anything but @ref
items. B6 joins the blocking doc_lint gate spec, with selftest fixtures
and header-relative locations in the gate report.
---
 .github/workflows/docs.yml                    |  8 +-
 doc/STYLE_GUIDE.md                            | 11 ++-
 doc/lint/README.md                            |  6 +-
 doc/lint/baseline.mjs                         |  8 +-
 doc/lint/doc-lint.mjs                         | 70 ++++++++++++++-
 doc/lint/selftest.mjs                         | 48 +++++++++-
 include/boost/corosio/delay.hpp               |  4 +-
 include/boost/corosio/endpoint.hpp            |  4 +-
 include/boost/corosio/io/io_object.hpp        |  3 +-
 include/boost/corosio/io/io_read_stream.hpp   |  5 +-
 include/boost/corosio/io/io_signal_set.hpp    |  3 +-
 include/boost/corosio/io/io_stream.hpp        |  2 +-
 include/boost/corosio/io/io_write_stream.hpp  |  5 +-
 include/boost/corosio/io_context.hpp          |  6 +-
 include/boost/corosio/ip_address.hpp          | 11 +--
 include/boost/corosio/ipv4_address.hpp        |  4 +-
 include/boost/corosio/ipv6_address.hpp        |  6 +-
 .../corosio/native/native_io_context.hpp      |  2 +-
 .../native/native_local_datagram_socket.hpp   |  2 +-
 .../native/native_local_stream_acceptor.hpp   |  3 +-
 .../native/native_local_stream_socket.hpp     |  2 +-
 .../native/native_posix_stream_descriptor.hpp |  2 +-
 .../native/native_random_access_file.hpp      |  2 +-
 .../boost/corosio/native/native_resolver.hpp  |  2 +-
 .../corosio/native/native_signal_set.hpp      |  9 +-
 .../corosio/native/native_socket_option.hpp   |  2 +-
 .../corosio/native/native_stream_file.hpp     |  2 +-
 .../corosio/native/native_tcp_acceptor.hpp    |  3 +-
 .../corosio/native/native_tcp_socket.hpp      |  2 +-
 .../corosio/native/native_udp_socket.hpp      |  2 +-
 .../native/native_win_object_handle.hpp       |  2 +-
 .../native_win_random_access_handle.hpp       |  2 +-
 .../native/native_win_stream_handle.hpp       |  2 +-
 include/boost/corosio/openssl_stream.hpp      |  2 +-
 .../boost/corosio/posix_stream_descriptor.hpp |  6 +-
 include/boost/corosio/random_access_file.hpp  |  2 +-
 include/boost/corosio/signal_set.hpp          | 11 ++-
 include/boost/corosio/socket_option.hpp       |  2 -
 include/boost/corosio/stream_file.hpp         |  2 +-
 include/boost/corosio/tcp_acceptor.hpp        |  6 +-
 include/boost/corosio/tcp_server.hpp          | 10 +--
 include/boost/corosio/test/mocket.hpp         |  3 +-
 include/boost/corosio/timeout.hpp             |  4 +-
 include/boost/corosio/tls_context.hpp         | 88 +++++++++----------
 include/boost/corosio/tls_stream.hpp          |  4 +-
 include/boost/corosio/wait_traits.hpp         |  2 +-
 include/boost/corosio/win_object_handle.hpp   |  6 +-
 .../corosio/win_random_access_handle.hpp      |  4 +-
 include/boost/corosio/win_stream_handle.hpp   |  4 +-
 include/boost/corosio/wolfssl_stream.hpp      | 10 +--
 50 files changed, 276 insertions(+), 135 deletions(-)

diff --git a/.github/workflows/docs.yml b/.github/workflows/docs.yml
index f6aa3e22b..df2cfed7e 100644
--- a/.github/workflows/docs.yml
+++ b/.github/workflows/docs.yml
@@ -309,7 +309,7 @@ jobs:
         working-directory: boost-root/libs/corosio/doc
         run: node lint/check-no-new-violations.mjs --show-baseline
 
-      # The gate: reports any NEW A1/A6/B2/D2/ANCHOR violation, any NEW MrDocs
+      # The gate: reports any NEW A1/A6/B2/B6/D2/ANCHOR violation, any NEW MrDocs
       # reference-surface warning, any NEW C2 sentence-length violation in the hard
       # slice, and any NEW C4/C9/C10 wording violation on EITHER surface.
       #
@@ -325,7 +325,7 @@ jobs:
       #     So `^C2:` is the correct shape THERE, and it deliberately cannot reach
       #     the `advisory-C2` slice (doc/STYLE_GUIDE.md C2 relaxes the 25-word limit
       #     for 2.networking-tutorial/, which is essay-style protocol theory).
-      #   * doc_lint is also rule-at-the-head, hence `^(A1|A6|B2|D2|ANCHOR):`. SHOULD
+      #   * doc_lint is also rule-at-the-head, hence `^(A1|A6|B2|B6|D2|ANCHOR):`. SHOULD
       #     a rule be added there, note SHAPE is deliberately excluded: it is an
       #     advisory content heuristic, not a defect.
       #
@@ -341,7 +341,7 @@ jobs:
       # THE GATE IS SPLIT IN TWO. Everything blocks EXCEPT the MrDocs
       # reference-surface check, and that exception is evidence-based.
       #
-      # A1/A6/B2/D2/ANCHOR, C2, and the C4/C9/C10/A7 wording rules are all STRICT.
+      # A1/A6/B2/B6/D2/ANCHOR, C2, and the C4/C9/C10/A7 wording rules are all STRICT.
       # baseline.json is now authored by this job (workflow_dispatch reseed), so a
       # strict comparison is CI-against-CI and carries no environment drift. The
       # wording rules additionally have an EMPTY gated subset — zero baselined
@@ -366,7 +366,7 @@ jobs:
         working-directory: boost-root/libs/corosio/doc
         run: |
           node lint/check-no-new-violations.mjs --strict \
-            --gate 'doc_lint:^(A1|A6|B2|D2|ANCHOR):' \
+            --gate 'doc_lint:^(A1|A6|B2|B6|D2|ANCHOR):' \
             --gate 'sentence_length:^C2:' \
             --gate 'vale_adoc:Corosio\.PartHeadings$' \
             --gate 'vale_adoc:(Corosio\.SimpleTense|Corosio\.NoFluff|Corosio\.Terminology)$' \
diff --git a/doc/STYLE_GUIDE.md b/doc/STYLE_GUIDE.md
index 5db0108ad..786ac7d91 100644
--- a/doc/STYLE_GUIDE.md
+++ b/doc/STYLE_GUIDE.md
@@ -104,6 +104,15 @@ The Antora pipeline provides two mechanisms; use them instead of hand-authoring:
   suppressions live in `test/doc/doc_warnings.hpp`, included once per file outside every tag; a
   warning that fires in one fragment stays in that fragment with a comment saying why. B5 is
   enforced by review only — no script checks it.
+- **B6. Every `@see` target in a docstring is an `@ref`.** Write `@see @ref delay, @ref wait_traits`,
+  never `@see delay, wait_traits`. MrDocs treats the text after `@see` as an ordinary paragraph
+  and does not auto-link names in it (Doxygen does), so a bare name renders as plain text in the
+  "See Also" section. Nothing warns about it either: `warn-broken-ref` checks only `@ref`
+  targets. Keep the line to the list of links. Prose after `@see` ("for the non-throwing form")
+  renders unlinked too, so move it into the description. When a name inside a class resolves
+  to the wrong symbol (`@ref tcp_server` inside `tcp_server::worker_base` finds the
+  constructor), qualify it. `doc-lint.mjs` checks every `@see` paragraph in the public
+  headers, including the lines it wraps onto.
 
 ## Part C — Wording (pragmatic Simplified Technical English)
 
@@ -250,7 +259,7 @@ Not every rule is machine-checkable. Each rule sits in one of three tiers:
 
 | Tier | Rules |
 |---|---|
-| **Gate** | A1, A6, A7, B2, B3, C2, C4, C9, C10, D2 |
+| **Gate** | A1, A6, A7, B2, B3, B6, C2, C4, C9, C10, D2 |
 | **Warning** | A2, B1, C1, C3, C5, C6, D4, D5, E1 |
 | **Review** | A3, A4, A5, B4, B5, C7, C8, C11, D1, D3, E2, E3, E4 |
 
diff --git a/doc/lint/README.md b/doc/lint/README.md
index 5ecfd6b3f..302381a77 100644
--- a/doc/lint/README.md
+++ b/doc/lint/README.md
@@ -17,7 +17,7 @@ rationale. What is Corosio-specific is recorded here.
 
 | Script | What it checks |
 |---|---|
-| `doc-lint.mjs` | Structural AsciiDoc/nav rules (A1, A6, B2, ANCHOR, SHAPE, D2). JSON on stdout. |
+| `doc-lint.mjs` | Structural AsciiDoc/nav rules (A1, A6, B2, ANCHOR, SHAPE, D2), plus B6 (`@see` without `@ref`) over the public headers. JSON on stdout. |
 | `extract-docstrings.mjs` | Extracts header docstrings into `.docstrings/*.adoc` so Vale can lint them. Doxygen targets (`@ref`/`@p`/`@c`/`@see`) are re-emitted as code spans, and `@par !example` directives are dropped — see below. |
 | `sentence-length.mjs` | **The authority for C2** (no sentence over 25 words), over both corpora. |
 | `check-include-tags.mjs` | Every `include::example$…[tag=…]` resolves to a live tag in a compiled source. |
@@ -213,7 +213,7 @@ The gate runs as two steps:
 
 | Step | Checks | Posture |
 |---|---|---|
-| `Lint: gate (BLOCKING)` | `doc_lint` (A1/A6/B2/D2/ANCHOR), `sentence_length` (C2), and the C4/C9/C10/A7 wording rules on both corpora | **`--strict`** |
+| `Lint: gate (BLOCKING)` | `doc_lint` (A1/A6/B2/B6/D2/ANCHOR), `sentence_length` (C2), and the C4/C9/C10/A7 wording rules on both corpora | **`--strict`** |
 | `Lint: gate (reference surface, reporting)` | `mrdocs_warnings` | reports, does not fail |
 
 `baseline.json` is now authored by the Documentation job itself, so a strict comparison is
@@ -237,7 +237,7 @@ pin that skipped this check on the first reseed. Promote it only alongside a pin
 >
 > ```sh
 > node lint/check-no-new-violations.mjs --strict \
->   --gate 'doc_lint:^(A1|A6|B2|D2|ANCHOR):' --gate 'sentence_length:^C2:' \
+>   --gate 'doc_lint:^(A1|A6|B2|B6|D2|ANCHOR):' --gate 'sentence_length:^C2:' \
 >   --gate 'vale_adoc:Corosio\.PartHeadings$' \
 >   --gate 'vale_adoc:(Corosio\.SimpleTense|Corosio\.NoFluff|Corosio\.Terminology)$' \
 >   --gate 'vale_docstrings:(Corosio\.SimpleTense|Corosio\.NoFluff|Corosio\.Terminology)$'
diff --git a/doc/lint/baseline.mjs b/doc/lint/baseline.mjs
index 52053893d..307fa2153 100644
--- a/doc/lint/baseline.mjs
+++ b/doc/lint/baseline.mjs
@@ -245,9 +245,13 @@ function docLintFingerprints() {
     for (const it of items) {
       const fp = occurrenceKey(seen, `${check}:${it.file}`, it.message);
       fingerprints.push(fp);
-      // doc-lint reports paths relative to the pages tree, not to doc/.
+      // doc-lint reports paths relative to the pages tree, not to doc/ --
+      // except B6, which scans headers and reports repo-relative paths.
       if (wantDetails) {
-        details[fp] = { ...resolveSource(`modules/ROOT/pages/${it.file}`, it.line ?? null, null),
+        const src = it.file.startsWith('include/')
+          ? { file: it.file, line: it.line ?? null }
+          : resolveSource(`modules/ROOT/pages/${it.file}`, it.line ?? null, null);
+        details[fp] = { ...src,
                         rule: check, message: it.message, excerpt: null };
       }
     }
diff --git a/doc/lint/doc-lint.mjs b/doc/lint/doc-lint.mjs
index b1ddfdf31..07b1cba22 100644
--- a/doc/lint/doc-lint.mjs
+++ b/doc/lint/doc-lint.mjs
@@ -61,6 +61,17 @@
 //        block-depth skip rather than a whole-file regex. Bite-test per
 //        style-guide F4: put `` `[[nodiscard]]` `` in a page and confirm
 //        ANCHOR fires.
+//   B6 — every `@see` line in a public header names its targets with
+//        `@ref`. MrDocs does not auto-link names in `@see` (Doxygen does),
+//        so `@see delay` renders as plain text in "See Also" and nothing
+//        warns: `warn-broken-ref` only checks `@ref` targets. The line must
+//        be `@see @ref a, @ref b` and nothing else; prose after `@see` also
+//        renders unlinked, so it fires too. The lines a `@see` paragraph
+//        wraps onto are held to the same rule. Scans include/boost/corosio
+//        minus detail/ (the same directories as extract-docstrings.mjs).
+//        This is the one rule here that reads headers, not pages, so its
+//        `file` is repo-relative (`include/...`). Bite-test per style-guide
+//        F4: write `@see delay` in a header and confirm B6 fires.
 //   D2 — every page in a CONCEPT_DIRS chapter (or quick-start.adoc) has
 //        >=1 include::example$. D2's "concept page" is a pedagogical
 //        category, not a Diátaxis mode — deliberately independent of
@@ -79,6 +90,8 @@ const ROOT = path.resolve(path.dirname(new URL(import.meta.url).pathname), '..')
 // pages-tree override is for (exercising B2 in isolation).
 const PAGES_DIR = process.argv[2] ? path.resolve(process.argv[2]) : path.join(ROOT, 'modules/ROOT/pages');
 const NAV_FILE = path.join(ROOT, 'modules/ROOT/nav.adoc');
+// B6's header tree; a second CLI arg overrides it for the self-test.
+const HEADERS_DIR = process.argv[3] ? path.resolve(process.argv[3]) : path.join(ROOT, '../include/boost/corosio');
 
 // The four Diátaxis modes doc/STYLE_GUIDE.md Part A defines. A1 rejects
 // anything else, including the legacy `concept` value (never a Diátaxis
@@ -264,7 +277,55 @@ function scanAnchors(lines) {
   return out;
 }
 
-const findings = { A1: [], A6: [], B2: [], SHAPE: [], ANCHOR: [], D2: [] };
+function walkHeaders(dir) {
+  let out = [];
+  for (const ent of fs.readdirSync(dir, { withFileTypes: true })) {
+    const p = path.join(dir, ent.name);
+    if (ent.isDirectory()) { if (ent.name !== 'detail') out = out.concat(walkHeaders(p)); }
+    else if (ent.name.endsWith('.hpp')) out.push(p);
+  }
+  return out;
+}
+
+// A `@see` paragraph holding anything other than `@ref name` items joined by
+// commas. The paragraph runs past the `@see` line, as Doxygen's does, until a
+// blank line, `*/`, a line opening with any command but `@ref`, or (for a
+// `///` comment) a line that is not `///`. Each offending line is reported.
+const SEE_LINE = /^(\s*)(\/\/\/)?\s*[@\\]see\b(.*)$/;
+const SEE_REF = /[@\\]ref\s+[\w:~<>]+(?:\([^)]*\))?/g;
+const NOT_REF_COMMAND = /^[@\\](?!ref\b)\w/;
+function scanSeeLines(lines) {
+  const out = [];
+  const check = (text, i) => {
+    const body = text.split('*/')[0];
+    if (body.replace(SEE_REF, '').replace(/[\s,]/g, '') !== '')
+      out.push({ line: i + 1, message: `@see entry without @ref renders unlinked: ${body.trim()}` });
+    return !text.includes('*/');
+  };
+  let open = false;   // inside a @see paragraph
+  let slashes = false; // ...that lives in a `///` run
+  lines.forEach((l, i) => {
+    const m = SEE_LINE.exec(l);
+    if (m) {
+      slashes = m[2] !== undefined;
+      open = check(m[3], i);
+      return;
+    }
+    if (!open) return;
+    let text = l;
+    if (slashes) {
+      const s = /^\s*\/\/\/(.*)$/.exec(l);
+      if (!s) { open = false; return; }
+      text = s[1];
+    }
+    const t = text.trim();
+    if (t === '' || t.startsWith('*/') || NOT_REF_COMMAND.test(t)) { open = false; return; }
+    open = check(text, i);
+  });
+  return out;
+}
+
+const findings = { A1: [], A6: [], B2: [], B6: [], SHAPE: [], ANCHOR: [], D2: [] };
 const files = walk(PAGES_DIR);
 
 for (const file of files) {
@@ -294,6 +355,13 @@ for (const file of files) {
   }
 }
 
+for (const file of walkHeaders(HEADERS_DIR)) {
+  const rel = path.join('include/boost/corosio', path.relative(HEADERS_DIR, file));
+  for (const s of scanSeeLines(fs.readFileSync(file, 'utf8').split('\n'))) {
+    findings.B6.push({ file: rel, line: s.line, message: s.message });
+  }
+}
+
 const navText = fs.readFileSync(NAV_FILE, 'utf8');
 const topEntries = navText.split('\n').filter(l => /^\* xref:/.test(l));
 const qsIndex = topEntries.findIndex(l => /quick-start/.test(l));
diff --git a/doc/lint/selftest.mjs b/doc/lint/selftest.mjs
index 1785e0825..851ca0d6b 100644
--- a/doc/lint/selftest.mjs
+++ b/doc/lint/selftest.mjs
@@ -403,7 +403,44 @@ try {
       '',
     ].join('\n'));
 
-    const d = spawnSync('node', [path.join(SCRIPT_DIR, 'doc-lint.mjs'), DOCLINT_TMP],
+    // B6 header fixture, passed to doc-lint.mjs as its header tree. Line
+    // numbers are asserted below: 3, 4 and 5 must fire; 6 and 7 must not.
+    // detail/ is outside B6's scope, so its bare `@see` must not fire either.
+    write('hdr/see.hpp', [
+      '/** Brief.',                                       // 1
+      '',                                                 // 2
+      '    @see delay',                                   // 3 <- must fire
+      '    @see @ref delay, wait_traits',                 // 4 <- must fire (one name unlinked)
+      '    @see @ref add, for the non-throwing form.',    // 5 <- must fire (prose)
+      '    @see @ref delay, @ref io_context_options::locking', // 6 <- must NOT fire
+      '    @see @ref accept(tcp_socket&)',                // 7 <- must NOT fire
+      '*/',
+      '',
+    ].join('\n'));
+    write('hdr/detail/hidden.hpp', '/** Brief.\n    @see delay\n*/\n');
+    // B6 continuation fixture: a `@see` paragraph wraps onto following lines
+    // until a blank line, `*/`, a non-@ref command, or the end of a `///` run.
+    // 3 and 12 must fire; nothing else may.
+    write('hdr/see-wrap.hpp', [
+      '/** Brief.',                                  // 1
+      '    @see @ref a,',                            // 2
+      '         b',                                  // 3  <- must fire (bare name, wrapped)
+      '    @see @ref a,',                            // 4
+      '         @ref b',                             // 5  <- must NOT fire (wrapped @ref)
+      '    @see @ref a',                             // 6
+      '',                                            // 7  blank line ends the paragraph
+      '    Plain prose after the list.',             // 8  <- must NOT fire
+      '    @see @ref a',                             // 9
+      '    @par Note',                               // 10 a command ends the paragraph
+      '    More prose.',                             // 11 <- must NOT fire
+      '    @see @ref a, b */',                       // 12 <- must fire (bare name before */)
+      '/// @see @ref a,',                            // 13
+      '///      @ref b',                             // 14 <- must NOT fire
+      'int prose_outside_the_comment;',              // 15 <- must NOT fire (/// run ended)
+      '',
+    ].join('\n'));
+
+    const d = spawnSync('node', [path.join(SCRIPT_DIR, 'doc-lint.mjs'), DOCLINT_TMP, path.join(DOCLINT_TMP, 'hdr')],
       { encoding: 'utf8', cwd: DOC_DIR, maxBuffer: 16 * 1024 * 1024 });
     check('doc-lint.mjs exits 0 against the B2 fixture tree', d.status === 0,
       `exited ${d.status}: ${(d.stderr || '').trim().slice(-200)}`);
@@ -498,6 +535,15 @@ try {
         `attr-anchor.adoc:10 is the passthrough fix and must not fire; got: ${JSON.stringify(anchorRule)}`);
       check('ANCHOR finds exactly the one planted prose violation',
         anchorRule.length === 1, `expected exactly 1 ANCHOR finding, got: ${JSON.stringify(anchorRule)}`);
+
+      // B6: MrDocs renders a bare `@see` name as plain text and warns about
+      // nothing, so a regression here would be silent on the site too.
+      const seeLines = dOut.findings.B6.map((f) => `${f.file}:${f.line}`).sort();
+      check('B6 flags exactly the bare-name, mixed and prose @see lines, nothing in detail/',
+        JSON.stringify(seeLines) === JSON.stringify(
+          ['include/boost/corosio/see-wrap.hpp:12', 'include/boost/corosio/see-wrap.hpp:3',
+           'include/boost/corosio/see.hpp:3', 'include/boost/corosio/see.hpp:4', 'include/boost/corosio/see.hpp:5']),
+        `got: ${JSON.stringify(seeLines)}`);
     }
   } finally {
     fs.rmSync(DOCLINT_TMP, { recursive: true, force: true });
diff --git a/include/boost/corosio/delay.hpp b/include/boost/corosio/delay.hpp
index ad41d5f53..7ad9cfc73 100644
--- a/include/boost/corosio/delay.hpp
+++ b/include/boost/corosio/delay.hpp
@@ -101,7 +101,7 @@ emplace_delay_timer(std::optional<timer>& t, capy::execution_context& ctx)
     auto-enabled at `concurrency_hint` == 1. Cross-thread cancellation
     requires a multi-threaded-capable context.
 
-    @see delay
+    @see @ref delay
 */
 class delay_awaitable
 {
@@ -217,7 +217,7 @@ class delay_awaitable
     resumes inline with `error::canceled`; stop while suspended
     cancels the pending wait, including between re-arms.
 
-    @see delay, wait_traits
+    @see @ref delay, @ref wait_traits
 */
 template<class Clock, class Traits>
 class clock_delay_awaitable
diff --git a/include/boost/corosio/endpoint.hpp b/include/boost/corosio/endpoint.hpp
index 41b145e01..ae728b0bc 100644
--- a/include/boost/corosio/endpoint.hpp
+++ b/include/boost/corosio/endpoint.hpp
@@ -91,11 +91,13 @@ class endpoint
         @li IPv6 without port: `::1` or `2001:db8::1`
         @li IPv6 with port (bracketed): `[::1]:8080`
 
+        @ref make_endpoint is the non-throwing form.
+
         @param s The string to parse.
 
         @throws std::system_error on parse failure.
 
-        @see make_endpoint for the non-throwing form.
+        @see @ref make_endpoint
     */
     explicit endpoint(std::string_view s);
 
diff --git a/include/boost/corosio/io/io_object.hpp b/include/boost/corosio/io/io_object.hpp
index f18cefcad..33cd4cc37 100644
--- a/include/boost/corosio/io/io_object.hpp
+++ b/include/boost/corosio/io/io_object.hpp
@@ -1,6 +1,7 @@
 //
 // Copyright (c) 2025 Vinnie Falco (vinnie.falco@gmail.com)
 // Copyright (c) 2026 Steve Gerbino
+// Copyright (c) 2026 Michael Vandeberg
 //
 // Distributed under the Boost Software License, Version 1.0. (See accompanying
 // file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt)
@@ -43,7 +44,7 @@ namespace boost::corosio {
     @note Intended as a protected base class. The handle member
         `h_` is accessible to derived classes.
 
-    @see io_stream, tcp_socket, tcp_acceptor
+    @see @ref io_stream, @ref tcp_socket, @ref tcp_acceptor
 */
 class BOOST_COROSIO_DECL io_object
 {
diff --git a/include/boost/corosio/io/io_read_stream.hpp b/include/boost/corosio/io/io_read_stream.hpp
index f27e059ee..53023e06f 100644
--- a/include/boost/corosio/io/io_read_stream.hpp
+++ b/include/boost/corosio/io/io_read_stream.hpp
@@ -1,5 +1,6 @@
 //
 // Copyright (c) 2026 Steve Gerbino
+// Copyright (c) 2026 Michael Vandeberg
 //
 // Distributed under the Boost Software License, Version 1.0. (See accompanying
 // file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt)
@@ -41,7 +42,7 @@ namespace boost::corosio {
     Distinct objects: Safe.
     Shared objects: Unsafe.
 
-    @see io_write_stream, io_stream, io_object
+    @see @ref io_write_stream, @ref io_stream, @ref io_object
 */
 class BOOST_COROSIO_DECL io_read_stream : virtual public io_object
 {
@@ -123,7 +124,7 @@ class BOOST_COROSIO_DECL io_read_stream : virtual public io_object
 
         @return An awaitable yielding `(error_code, std::size_t)`.
 
-        @see io_stream::write_some
+        @see @ref io_stream::write_some
     */
     template<capy::MutableBufferSequence MB>
     [[nodiscard]] auto read_some(MB const& buffers)
diff --git a/include/boost/corosio/io/io_signal_set.hpp b/include/boost/corosio/io/io_signal_set.hpp
index eb174fa46..77c5740b6 100644
--- a/include/boost/corosio/io/io_signal_set.hpp
+++ b/include/boost/corosio/io/io_signal_set.hpp
@@ -1,5 +1,6 @@
 //
 // Copyright (c) 2026 Steve Gerbino
+// Copyright (c) 2026 Michael Vandeberg
 //
 // Distributed under the Boost Software License, Version 1.0. (See accompanying
 // file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt)
@@ -36,7 +37,7 @@ namespace boost::corosio {
     Distinct objects: Safe.
     Shared objects: Unsafe.
 
-    @see signal_set, io_object
+    @see @ref signal_set, @ref io_object
 */
 class BOOST_COROSIO_DECL io_signal_set : public io_object
 {
diff --git a/include/boost/corosio/io/io_stream.hpp b/include/boost/corosio/io/io_stream.hpp
index 7fdc4bba5..d1abdd557 100644
--- a/include/boost/corosio/io/io_stream.hpp
+++ b/include/boost/corosio/io/io_stream.hpp
@@ -56,7 +56,7 @@ namespace boost::corosio {
     @par Example
     @par !example io_stream
 
-    @see io_read_stream, io_write_stream, tcp_socket
+    @see @ref io_read_stream, @ref io_write_stream, @ref tcp_socket
 */
 class BOOST_COROSIO_DECL io_stream
     : public io_read_stream
diff --git a/include/boost/corosio/io/io_write_stream.hpp b/include/boost/corosio/io/io_write_stream.hpp
index bd2055d97..30f8bb231 100644
--- a/include/boost/corosio/io/io_write_stream.hpp
+++ b/include/boost/corosio/io/io_write_stream.hpp
@@ -1,5 +1,6 @@
 //
 // Copyright (c) 2026 Steve Gerbino
+// Copyright (c) 2026 Michael Vandeberg
 //
 // Distributed under the Boost Software License, Version 1.0. (See accompanying
 // file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt)
@@ -41,7 +42,7 @@ namespace boost::corosio {
     Distinct objects: Safe.
     Shared objects: Unsafe.
 
-    @see io_read_stream, io_stream, io_object
+    @see @ref io_read_stream, @ref io_stream, @ref io_object
 */
 class BOOST_COROSIO_DECL io_write_stream : virtual public io_object
 {
@@ -122,7 +123,7 @@ class BOOST_COROSIO_DECL io_write_stream : virtual public io_object
 
         @return An awaitable yielding `(error_code, std::size_t)`.
 
-        @see io_stream::read_some
+        @see @ref io_stream::read_some
     */
     template<capy::ConstBufferSequence CB>
     [[nodiscard]] auto write_some(CB const& buffers)
diff --git a/include/boost/corosio/io_context.hpp b/include/boost/corosio/io_context.hpp
index d21822df5..3addeb4c4 100644
--- a/include/boost/corosio/io_context.hpp
+++ b/include/boost/corosio/io_context.hpp
@@ -36,7 +36,7 @@ namespace boost::corosio {
     from the `concurrency_hint`. (The reverse does apply: a lockless tier
     reduces the effective hint used for performance tuning to 1.)
 
-    @see io_context_options::locking
+    @see @ref io_context_options::locking
 */
 enum class locking_mode
 {
@@ -77,7 +77,7 @@ enum class locking_mode
     @par Example
     @par !example configure
 
-    @see io_context, native_io_context
+    @see @ref io_context, @ref native_io_context
 */
 struct io_context_options
 {
@@ -235,7 +235,7 @@ effective_concurrency_hint(
     lockless @ref io_context_options::locking tier (`unsafe_io` or
     `unsafe`), in which case a single thread must drive it.
 
-    @see epoll_t, select_t, kqueue_t, iocp_t
+    @see @ref epoll_t, @ref select_t, @ref kqueue_t, @ref iocp_t
 */
 class BOOST_COROSIO_DECL io_context : public capy::execution_context
 {
diff --git a/include/boost/corosio/ip_address.hpp b/include/boost/corosio/ip_address.hpp
index 1727737b3..92635f4cf 100644
--- a/include/boost/corosio/ip_address.hpp
+++ b/include/boost/corosio/ip_address.hpp
@@ -1,6 +1,7 @@
 //
 // Copyright (c) 2026 Vinnie Falco (vinnie.falco@gmail.com)
 // Copyright (c) 2026 Steve Gerbino
+// Copyright (c) 2026 Michael Vandeberg
 //
 // Distributed under the Boost Software License, Version 1.0. (See accompanying
 // file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt)
@@ -56,7 +57,7 @@ namespace boost::corosio {
     @see
         @ref ipv4_address,
         @ref ipv6_address,
-        @ref make_ip_address.
+        @ref make_ip_address
 */
 class BOOST_COROSIO_DECL ip_address
 {
@@ -119,7 +120,7 @@ class BOOST_COROSIO_DECL ip_address
         @param s The string to parse.
 
         @see
-            @ref make_ip_address.
+            @ref make_ip_address
     */
     explicit ip_address(std::string_view s);
 
@@ -189,7 +190,7 @@ class BOOST_COROSIO_DECL ip_address
         IPv4-Mapped IPv6 Address (`::ffff:a.b.c.d`).
 
         @see
-            @ref to_v4.
+            @ref to_v4
     */
     bool is_v4_mapped() const noexcept
     {
@@ -208,7 +209,7 @@ class BOOST_COROSIO_DECL ip_address
         @return The IPv4 form of the address.
 
         @see
-            @ref is_v4, @ref is_v4_mapped.
+            @ref is_v4, @ref is_v4_mapped
     */
     ipv4_address to_v4() const
     {
@@ -226,7 +227,7 @@ class BOOST_COROSIO_DECL ip_address
         @return The held IPv6 address.
 
         @see
-            @ref is_v6.
+            @ref is_v6
     */
     ipv6_address to_v6() const
     {
diff --git a/include/boost/corosio/ipv4_address.hpp b/include/boost/corosio/ipv4_address.hpp
index 202e7329e..ee8588915 100644
--- a/include/boost/corosio/ipv4_address.hpp
+++ b/include/boost/corosio/ipv4_address.hpp
@@ -49,7 +49,7 @@ namespace boost::corosio {
 
     @see
         @ref make_ipv4_address,
-        @ref ipv6_address.
+        @ref ipv6_address
 */
 class BOOST_COROSIO_DECL ipv4_address
 {
@@ -130,7 +130,7 @@ class BOOST_COROSIO_DECL ipv4_address
             >3.2.2. Host (rfc3986)</a>
 
         @see
-            @ref make_ipv4_address.
+            @ref make_ipv4_address
     */
     explicit ipv4_address(std::string_view s);
 
diff --git a/include/boost/corosio/ipv6_address.hpp b/include/boost/corosio/ipv6_address.hpp
index b0258bfc8..25702c0a0 100644
--- a/include/boost/corosio/ipv6_address.hpp
+++ b/include/boost/corosio/ipv6_address.hpp
@@ -68,7 +68,7 @@ namespace boost::corosio {
 
     @see
         @ref ipv4_address,
-        @ref make_ipv6_address.
+        @ref make_ipv6_address
 */
 class BOOST_COROSIO_DECL ipv6_address
 {
@@ -182,7 +182,7 @@ class BOOST_COROSIO_DECL ipv6_address
             >3.2.2. Host (rfc3986)</a>
 
         @see
-            @ref make_ipv6_address.
+            @ref make_ipv6_address
     */
     explicit ipv6_address(std::string_view s);
 
@@ -288,7 +288,7 @@ class BOOST_COROSIO_DECL ipv6_address
             2.5.5.2. IPv4-Mapped IPv6 Address (rfc4291)</a>
 
         @see
-            @ref is_v4_mapped.
+            @ref is_v4_mapped
     */
     ipv4_address to_v4() const;
 
diff --git a/include/boost/corosio/native/native_io_context.hpp b/include/boost/corosio/native/native_io_context.hpp
index 7c5fae7e0..e4b821e3b 100644
--- a/include/boost/corosio/native/native_io_context.hpp
+++ b/include/boost/corosio/native/native_io_context.hpp
@@ -58,7 +58,7 @@ namespace boost::corosio {
     @par Example
     @par !example poll
 
-    @see io_context, epoll_t, iocp_t
+    @see @ref io_context, @ref epoll_t, @ref iocp_t
 */
 template<auto Backend>
 class native_io_context : public io_context
diff --git a/include/boost/corosio/native/native_local_datagram_socket.hpp b/include/boost/corosio/native/native_local_datagram_socket.hpp
index e6b76e73d..3eee4461f 100644
--- a/include/boost/corosio/native/native_local_datagram_socket.hpp
+++ b/include/boost/corosio/native/native_local_datagram_socket.hpp
@@ -65,7 +65,7 @@ namespace boost::corosio {
     @par Example
     @par !example open_bind_recv
 
-    @see local_datagram_socket, epoll_t, iocp_t
+    @see @ref local_datagram_socket, @ref epoll_t, @ref iocp_t
 */
 template<auto Backend>
 class native_local_datagram_socket : public local_datagram_socket
diff --git a/include/boost/corosio/native/native_local_stream_acceptor.hpp b/include/boost/corosio/native/native_local_stream_acceptor.hpp
index 7d5d2d6c7..e654e5283 100644
--- a/include/boost/corosio/native/native_local_stream_acceptor.hpp
+++ b/include/boost/corosio/native/native_local_stream_acceptor.hpp
@@ -1,5 +1,6 @@
 //
 // Copyright (c) 2026 Steve Gerbino
+// Copyright (c) 2026 Michael Vandeberg
 //
 // Distributed under the Boost Software License, Version 1.0. (See accompanying
 // file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt)
@@ -61,7 +62,7 @@ namespace boost::corosio {
     @par Thread Safety
     Same as @ref local_stream_acceptor.
 
-    @see local_stream_acceptor, epoll_t, iocp_t
+    @see @ref local_stream_acceptor, @ref epoll_t, @ref iocp_t
 */
 template<auto Backend>
 class native_local_stream_acceptor : public local_stream_acceptor
diff --git a/include/boost/corosio/native/native_local_stream_socket.hpp b/include/boost/corosio/native/native_local_stream_socket.hpp
index 3d71f5dd1..8f7571b65 100644
--- a/include/boost/corosio/native/native_local_stream_socket.hpp
+++ b/include/boost/corosio/native/native_local_stream_socket.hpp
@@ -63,7 +63,7 @@ namespace boost::corosio {
     @par Example
     @par !example connect
 
-    @see local_stream_socket, epoll_t, iocp_t
+    @see @ref local_stream_socket, @ref epoll_t, @ref iocp_t
 */
 template<auto Backend>
 class native_local_stream_socket : public local_stream_socket
diff --git a/include/boost/corosio/native/native_posix_stream_descriptor.hpp b/include/boost/corosio/native/native_posix_stream_descriptor.hpp
index 77a013730..1d3b31cda 100644
--- a/include/boost/corosio/native/native_posix_stream_descriptor.hpp
+++ b/include/boost/corosio/native/native_posix_stream_descriptor.hpp
@@ -62,7 +62,7 @@ namespace boost::corosio {
     @par Example
     @par !example assign_and_wait
 
-    @see posix_stream_descriptor, epoll_t, kqueue_t
+    @see @ref posix_stream_descriptor, @ref epoll_t, @ref kqueue_t
 */
 template<auto Backend>
 class native_posix_stream_descriptor : public posix_stream_descriptor
diff --git a/include/boost/corosio/native/native_random_access_file.hpp b/include/boost/corosio/native/native_random_access_file.hpp
index 8ab17d2df..32b79e975 100644
--- a/include/boost/corosio/native/native_random_access_file.hpp
+++ b/include/boost/corosio/native/native_random_access_file.hpp
@@ -63,7 +63,7 @@ namespace boost::corosio {
     @par Example
     @par !example native_random_access_file
 
-    @see random_access_file, epoll_t, iocp_t
+    @see @ref random_access_file, @ref epoll_t, @ref iocp_t
 */
 template<auto Backend>
 class native_random_access_file : public random_access_file
diff --git a/include/boost/corosio/native/native_resolver.hpp b/include/boost/corosio/native/native_resolver.hpp
index 8a15ab046..1a521f66d 100644
--- a/include/boost/corosio/native/native_resolver.hpp
+++ b/include/boost/corosio/native/native_resolver.hpp
@@ -46,7 +46,7 @@ namespace boost::corosio {
     @par Thread Safety
     Same as @ref resolver.
 
-    @see resolver, epoll_t, iocp_t
+    @see @ref resolver, @ref epoll_t, @ref iocp_t
 */
 template<auto Backend>
 class native_resolver : public resolver
diff --git a/include/boost/corosio/native/native_signal_set.hpp b/include/boost/corosio/native/native_signal_set.hpp
index 92b36fde1..72619670a 100644
--- a/include/boost/corosio/native/native_signal_set.hpp
+++ b/include/boost/corosio/native/native_signal_set.hpp
@@ -1,5 +1,6 @@
 //
 // Copyright (c) 2026 Steve Gerbino
+// Copyright (c) 2026 Michael Vandeberg
 //
 // Distributed under the Boost Software License, Version 1.0. (See accompanying
 // file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt)
@@ -45,7 +46,7 @@ namespace boost::corosio {
     @par Thread Safety
     Same as @ref signal_set.
 
-    @see signal_set, epoll_t, iocp_t
+    @see @ref signal_set, @ref epoll_t, @ref iocp_t
 */
 template<auto Backend>
 class native_signal_set : public signal_set
@@ -87,14 +88,16 @@ class native_signal_set : public signal_set
 
     /** Construct a native signal set with initial signals.
 
+        For the non-throwing form, construct with the context alone,
+        then call @ref signal_set::add for each signal.
+
         @param ctx The execution context that owns this signal set.
         @param signal First signal number to add.
         @param signals Additional signal numbers to add.
 
         @throws std::system_error on failure.
 
-        @see add for the non-throwing form: construct with the
-            context alone, then `add()` each signal.
+        @see @ref signal_set::add
     */
     template<std::convertible_to<int>... Signals>
     native_signal_set(
diff --git a/include/boost/corosio/native/native_socket_option.hpp b/include/boost/corosio/native/native_socket_option.hpp
index 300585c06..ceb93420c 100644
--- a/include/boost/corosio/native/native_socket_option.hpp
+++ b/include/boost/corosio/native/native_socket_option.hpp
@@ -24,7 +24,7 @@
     interchangeably with `tcp_socket::set_option` /
     `tcp_socket::get_option` and the corresponding acceptor methods.
 
-    @see boost::corosio::socket_option
+    @see @ref boost::corosio::socket_option
 */
 
 #ifndef BOOST_COROSIO_NATIVE_NATIVE_SOCKET_OPTION_HPP
diff --git a/include/boost/corosio/native/native_stream_file.hpp b/include/boost/corosio/native/native_stream_file.hpp
index 868276e42..083ee92e9 100644
--- a/include/boost/corosio/native/native_stream_file.hpp
+++ b/include/boost/corosio/native/native_stream_file.hpp
@@ -63,7 +63,7 @@ namespace boost::corosio {
     @par Example
     @par !example native_stream_file
 
-    @see stream_file, epoll_t, iocp_t
+    @see @ref stream_file, @ref epoll_t, @ref iocp_t
 */
 template<auto Backend>
 class native_stream_file : public stream_file
diff --git a/include/boost/corosio/native/native_tcp_acceptor.hpp b/include/boost/corosio/native/native_tcp_acceptor.hpp
index 15d115e39..902016fa0 100644
--- a/include/boost/corosio/native/native_tcp_acceptor.hpp
+++ b/include/boost/corosio/native/native_tcp_acceptor.hpp
@@ -1,5 +1,6 @@
 //
 // Copyright (c) 2026 Steve Gerbino
+// Copyright (c) 2026 Michael Vandeberg
 //
 // Distributed under the Boost Software License, Version 1.0. (See accompanying
 // file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt)
@@ -56,7 +57,7 @@ namespace boost::corosio {
     @par Thread Safety
     Same as @ref tcp_acceptor.
 
-    @see tcp_acceptor, epoll_t, iocp_t
+    @see @ref tcp_acceptor, @ref epoll_t, @ref iocp_t
 */
 template<auto Backend>
 class native_tcp_acceptor : public tcp_acceptor
diff --git a/include/boost/corosio/native/native_tcp_socket.hpp b/include/boost/corosio/native/native_tcp_socket.hpp
index 06b8386e5..bf89445d3 100644
--- a/include/boost/corosio/native/native_tcp_socket.hpp
+++ b/include/boost/corosio/native/native_tcp_socket.hpp
@@ -63,7 +63,7 @@ namespace boost::corosio {
     @par Example
     @par !example native_tcp_socket
 
-    @see tcp_socket, epoll_t, iocp_t
+    @see @ref tcp_socket, @ref epoll_t, @ref iocp_t
 */
 template<auto Backend>
 class native_tcp_socket : public tcp_socket
diff --git a/include/boost/corosio/native/native_udp_socket.hpp b/include/boost/corosio/native/native_udp_socket.hpp
index aeea89d50..b6992ce74 100644
--- a/include/boost/corosio/native/native_udp_socket.hpp
+++ b/include/boost/corosio/native/native_udp_socket.hpp
@@ -63,7 +63,7 @@ namespace boost::corosio {
     @par Example
     @par !example native_udp_socket
 
-    @see udp_socket, epoll_t
+    @see @ref udp_socket, @ref epoll_t
 */
 template<auto Backend>
 class native_udp_socket : public udp_socket
diff --git a/include/boost/corosio/native/native_win_object_handle.hpp b/include/boost/corosio/native/native_win_object_handle.hpp
index 62583390a..c9de2f5a5 100644
--- a/include/boost/corosio/native/native_win_object_handle.hpp
+++ b/include/boost/corosio/native/native_win_object_handle.hpp
@@ -42,7 +42,7 @@ namespace boost::corosio {
     @par Thread Safety
     Same as @ref win_object_handle.
 
-    @see win_object_handle, iocp_t
+    @see @ref win_object_handle, @ref iocp_t
 */
 template<auto Backend>
 class native_win_object_handle : public win_object_handle
diff --git a/include/boost/corosio/native/native_win_random_access_handle.hpp b/include/boost/corosio/native/native_win_random_access_handle.hpp
index dc0bcca75..a5b8d55ba 100644
--- a/include/boost/corosio/native/native_win_random_access_handle.hpp
+++ b/include/boost/corosio/native/native_win_random_access_handle.hpp
@@ -46,7 +46,7 @@ namespace boost::corosio {
     @par Example
     @par !example native_win_random_access_handle
 
-    @see win_random_access_handle, iocp_t
+    @see @ref win_random_access_handle, @ref iocp_t
 */
 template<auto Backend>
 class native_win_random_access_handle : public win_random_access_handle
diff --git a/include/boost/corosio/native/native_win_stream_handle.hpp b/include/boost/corosio/native/native_win_stream_handle.hpp
index c15fcf844..ffdb48789 100644
--- a/include/boost/corosio/native/native_win_stream_handle.hpp
+++ b/include/boost/corosio/native/native_win_stream_handle.hpp
@@ -43,7 +43,7 @@ namespace boost::corosio {
     @par Thread Safety
     Same as @ref win_stream_handle.
 
-    @see win_stream_handle, iocp_t
+    @see @ref win_stream_handle, @ref iocp_t
 */
 template<auto Backend>
 class native_win_stream_handle : public win_stream_handle
diff --git a/include/boost/corosio/openssl_stream.hpp b/include/boost/corosio/openssl_stream.hpp
index b7f174990..1b2ad954e 100644
--- a/include/boost/corosio/openssl_stream.hpp
+++ b/include/boost/corosio/openssl_stream.hpp
@@ -60,7 +60,7 @@ namespace boost::corosio {
     @par Example
     @par !example openssl_stream
 
-    @see tls_stream, wolfssl_stream
+    @see @ref tls_stream, @ref wolfssl_stream
 */
 class BOOST_COROSIO_DECL openssl_stream final : public tls_stream
 {
diff --git a/include/boost/corosio/posix_stream_descriptor.hpp b/include/boost/corosio/posix_stream_descriptor.hpp
index f467a547b..34e0be433 100644
--- a/include/boost/corosio/posix_stream_descriptor.hpp
+++ b/include/boost/corosio/posix_stream_descriptor.hpp
@@ -132,7 +132,7 @@ namespace boost::corosio {
     operations of the same type (e.g. two simultaneous reads). One
     read and one write may be in flight simultaneously.
 
-    @see io_stream, stream_file, wait_type
+    @see @ref io_stream, @ref stream_file, @ref wait_type
 */
 class BOOST_COROSIO_DECL posix_stream_descriptor : public io_stream
 {
@@ -292,7 +292,7 @@ class BOOST_COROSIO_DECL posix_stream_descriptor : public io_stream
         Throws nothing. On failure the object is unchanged and @p fd
         stays with the caller.
 
-        @see release
+        @see @ref release
     */
     [[nodiscard]] std::error_code assign(native_handle_type fd) noexcept;
 
@@ -353,7 +353,7 @@ class BOOST_COROSIO_DECL posix_stream_descriptor : public io_stream
         @par Example
         @par !example wait
 
-        @see wait_type
+        @see @ref wait_type
     */
     [[nodiscard]] wait_awaitable wait(wait_type w)
     {
diff --git a/include/boost/corosio/random_access_file.hpp b/include/boost/corosio/random_access_file.hpp
index ecdf2cb65..d2408d788 100644
--- a/include/boost/corosio/random_access_file.hpp
+++ b/include/boost/corosio/random_access_file.hpp
@@ -458,7 +458,7 @@ class BOOST_COROSIO_DECL random_access_file : public io_object
             read or write then fails with `ESPIPE` on the epoll,
             kqueue, and select I/O backends.
 
-        @see release
+        @see @ref release
     */
     [[nodiscard]] std::error_code assign(native_handle_type handle) noexcept;
 
diff --git a/include/boost/corosio/signal_set.hpp b/include/boost/corosio/signal_set.hpp
index cbee7c5ba..375db4fc5 100644
--- a/include/boost/corosio/signal_set.hpp
+++ b/include/boost/corosio/signal_set.hpp
@@ -197,14 +197,16 @@ class BOOST_COROSIO_DECL signal_set : public io_signal_set
 
     /** Construct a signal set with initial signals.
 
+        For the non-throwing form, construct with the context alone,
+        then call @ref add for each signal.
+
         @param ctx The execution context that owns this signal set.
         @param signal First signal number to add.
         @param signals Additional signal numbers to add.
 
         @throws std::system_error Thrown on failure.
 
-        @see add for the non-throwing form: construct with the
-            context alone, then `add()` each signal.
+        @see @ref add
     */
     template<std::convertible_to<int>... Signals>
     signal_set(capy::execution_context& ctx, int signal, Signals... signals)
@@ -234,6 +236,8 @@ class BOOST_COROSIO_DECL signal_set : public io_signal_set
     /** Construct a signal set with initial signals from an executor.
 
         The signal set is associated with the executor's context.
+        For the non-throwing form, construct with the executor alone,
+        then call @ref add for each signal.
 
         @param ex The executor whose context owns this signal set.
         @param signal First signal number to add.
@@ -241,8 +245,7 @@ class BOOST_COROSIO_DECL signal_set : public io_signal_set
 
         @throws std::system_error Thrown on failure.
 
-        @see add for the non-throwing form: construct with the
-            executor alone, then `add()` each signal.
+        @see @ref add
     */
     template<class Ex, std::convertible_to<int>... Signals>
         requires capy::Executor<Ex>
diff --git a/include/boost/corosio/socket_option.hpp b/include/boost/corosio/socket_option.hpp
index bcb42a985..872753587 100644
--- a/include/boost/corosio/socket_option.hpp
+++ b/include/boost/corosio/socket_option.hpp
@@ -33,8 +33,6 @@
     Both variants satisfy the same option-type interface and work
     interchangeably with `tcp_socket::set_option` /
     `tcp_socket::get_option` and the corresponding acceptor methods.
-
-    @see native_socket_option
 */
 
 namespace boost::corosio::socket_option {
diff --git a/include/boost/corosio/stream_file.hpp b/include/boost/corosio/stream_file.hpp
index a113b9b56..aa27993aa 100644
--- a/include/boost/corosio/stream_file.hpp
+++ b/include/boost/corosio/stream_file.hpp
@@ -330,7 +330,7 @@ class BOOST_COROSIO_DECL stream_file : public io_stream
             read or write then fails with `ESPIPE` on the epoll,
             kqueue, and select I/O backends.
 
-        @see release
+        @see @ref release
     */
     [[nodiscard]] std::error_code assign(native_handle_type handle) noexcept;
 
diff --git a/include/boost/corosio/tcp_acceptor.hpp b/include/boost/corosio/tcp_acceptor.hpp
index fa693ea4e..c83d76859 100644
--- a/include/boost/corosio/tcp_acceptor.hpp
+++ b/include/boost/corosio/tcp_acceptor.hpp
@@ -307,7 +307,7 @@ class BOOST_COROSIO_DECL tcp_acceptor : public io_object
         @par Example
         @par !example open
 
-        @see bind, listen
+        @see @ref bind, @ref listen
 
         @return The error code, empty on success.
     */
@@ -395,7 +395,7 @@ class BOOST_COROSIO_DECL tcp_acceptor : public io_object
         @par Example
         @par !example accept_into_a_reused_socket
 
-        @see accept()
+        @see @ref accept()
     */
     [[nodiscard]] auto accept(tcp_socket& peer)
     {
@@ -435,7 +435,7 @@ class BOOST_COROSIO_DECL tcp_acceptor : public io_object
         @par Example
         @par !example accept_returning_a_new_socket
 
-        @see accept(tcp_socket&)
+        @see @ref accept(tcp_socket&)
     */
     [[nodiscard]] auto accept()
     {
diff --git a/include/boost/corosio/tcp_server.hpp b/include/boost/corosio/tcp_server.hpp
index f38db98b0..9463783f7 100644
--- a/include/boost/corosio/tcp_server.hpp
+++ b/include/boost/corosio/tcp_server.hpp
@@ -98,7 +98,7 @@ namespace boost::corosio {
     @par Example
     @par !example custom_worker
 
-    @see worker_base, set_workers, launcher
+    @see @ref worker_base, @ref set_workers, @ref launcher
 */
 class BOOST_COROSIO_DECL tcp_server
 {
@@ -573,7 +573,7 @@ class BOOST_COROSIO_DECL tcp_server
         @par Thread Safety
         run() and socket() execute on the server's executor.
 
-        @see tcp_server, launcher
+        @see @ref boost::corosio::tcp_server, @ref launcher
     */
     class BOOST_COROSIO_DECL worker_base
     {
@@ -630,7 +630,7 @@ class BOOST_COROSIO_DECL tcp_server
         abandoned before it completes, as when the execution context
         holding it is destroyed.
 
-        @see worker_base::run
+        @see @ref worker_base::run
     */
     class BOOST_COROSIO_DECL launcher
     {
@@ -973,7 +973,7 @@ class BOOST_COROSIO_DECL tcp_server
         @par Thread Safety
         Not thread safe.
 
-        @see join, start
+        @see @ref join, @ref start
     */
     void stop();
 
@@ -1002,7 +1002,7 @@ class BOOST_COROSIO_DECL tcp_server
         May be called from any thread. It deadlocks if called
         from within the `io_context` event loop or from a worker coroutine.
 
-        @see stop, start
+        @see @ref stop, @ref start
     */
     void join();
 
diff --git a/include/boost/corosio/test/mocket.hpp b/include/boost/corosio/test/mocket.hpp
index c334a56b8..3632661ba 100644
--- a/include/boost/corosio/test/mocket.hpp
+++ b/include/boost/corosio/test/mocket.hpp
@@ -1,6 +1,7 @@
 //
 // Copyright (c) 2025 Vinnie Falco (vinnie.falco@gmail.com)
 // Copyright (c) 2026 Steve Gerbino
+// Copyright (c) 2026 Michael Vandeberg
 //
 // Distributed under the Boost Software License, Version 1.0. (See accompanying
 // file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt)
@@ -57,7 +58,7 @@ namespace boost::corosio::test {
     All coroutines using the mocket must be suspended when calling
     `expect()` or `provide()`.
 
-    @see make_mocket_pair
+    @see @ref make_mocket_pair
 */
 template<class Socket = tcp_socket>
 class basic_mocket
diff --git a/include/boost/corosio/timeout.hpp b/include/boost/corosio/timeout.hpp
index fd14f06d0..3846b2816 100644
--- a/include/boost/corosio/timeout.hpp
+++ b/include/boost/corosio/timeout.hpp
@@ -55,7 +55,7 @@ namespace boost::corosio {
     @return An awaitable yielding `results` matching the inner
         awaitable's result type.
 
-    @see delay
+    @see @ref delay
 */
 template<capy::ContextAwaitable A, typename Rep, typename Period>
     requires detail::is_results_v<
@@ -88,7 +88,7 @@ timeout(A a, std::chrono::duration<Rep, Period> dur)
     @return An awaitable yielding `results` matching the inner
         awaitable's result type.
 
-    @see delay
+    @see @ref delay
 */
 template<capy::ContextAwaitable A>
     requires detail::is_results_v<
diff --git a/include/boost/corosio/tls_context.hpp b/include/boost/corosio/tls_context.hpp
index cd9e35864..3a5e4c5cf 100644
--- a/include/boost/corosio/tls_context.hpp
+++ b/include/boost/corosio/tls_context.hpp
@@ -31,8 +31,8 @@ namespace boost::corosio {
     Specifies the minimum or maximum TLS protocol version to use
     for connections. Only modern, secure versions are supported.
 
-    @see tls_context::set_min_protocol_version
-    @see tls_context::set_max_protocol_version
+    @see @ref tls_context::set_min_protocol_version
+    @see @ref tls_context::set_max_protocol_version
 */
 enum class tls_version
 {
@@ -47,8 +47,8 @@ enum class tls_version
 
     Specifies the encoding format for certificate and key data.
 
-    @see tls_context::use_certificate
-    @see tls_context::use_private_key
+    @see @ref tls_context::use_certificate
+    @see @ref tls_context::use_private_key
 */
 enum class tls_file_format
 {
@@ -64,7 +64,7 @@ enum class tls_file_format
     Controls how the TLS implementation verifies the peer's
     certificate during the handshake.
 
-    @see tls_context::set_verify_mode
+    @see @ref tls_context::set_verify_mode
 */
 enum class tls_verify_mode
 {
@@ -83,7 +83,7 @@ enum class tls_verify_mode
     Controls how certificate revocation status is checked during
     verification.
 
-    @see tls_context::set_revocation_policy
+    @see @ref tls_context::set_revocation_policy
 */
 enum class tls_revocation_policy
 {
@@ -102,7 +102,7 @@ enum class tls_revocation_policy
     Indicates whether the password is needed for reading (decrypting)
     or writing (encrypting) key material.
 
-    @see tls_context::set_password_callback
+    @see @ref tls_context::set_password_callback
 */
 enum class tls_password_purpose
 {
@@ -134,7 +134,7 @@ class tls_context;
     backend and are valid only for the duration of a single callback
     invocation. Do not retain them beyond the call.
 
-    @see tls_context::set_verify_callback
+    @see @ref tls_context::set_verify_callback
 */
 class verify_context
 {
@@ -235,7 +235,7 @@ tls_context_data const& get_tls_context_data(tls_context const&) noexcept;
     @par Example
     @par !example tls_context
 
-    @see tls_role
+    @see @ref tls_role
 */
 class BOOST_COROSIO_DECL tls_context
 {
@@ -318,8 +318,8 @@ class BOOST_COROSIO_DECL tls_context
             native context is first built; a malformed certificate surfaces
             as a handshake failure.
 
-        @see use_certificate_file
-        @see use_private_key
+        @see @ref use_certificate_file
+        @see @ref use_private_key
     */
     [[nodiscard]] std::error_code
     use_certificate(std::string_view certificate, tls_file_format format);
@@ -341,8 +341,8 @@ class BOOST_COROSIO_DECL tls_context
         @par Example
         @par !example use_certificate_file
 
-        @see use_certificate
-        @see use_private_key_file
+        @see @ref use_certificate
+        @see @ref use_private_key_file
     */
     [[nodiscard]] std::error_code
     use_certificate_file(std::string_view filename, tls_file_format format);
@@ -360,7 +360,7 @@ class BOOST_COROSIO_DECL tls_context
             context is first built; a malformed chain surfaces as a
             handshake failure.
 
-        @see use_certificate_chain_file
+        @see @ref use_certificate_chain_file
     */
     [[nodiscard]] std::error_code use_certificate_chain(std::string_view chain);
 
@@ -379,7 +379,7 @@ class BOOST_COROSIO_DECL tls_context
         @par Example
         @par !example use_certificate_chain_file
 
-        @see use_certificate_chain
+        @see @ref use_certificate_chain
     */
     [[nodiscard]] std::error_code
     use_certificate_chain_file(std::string_view filename);
@@ -402,8 +402,8 @@ class BOOST_COROSIO_DECL tls_context
         failure: a malformed key, a missing password callback for an
         encrypted key, and a certificate mismatch.
 
-        @see use_private_key_file
-        @see set_password_callback
+        @see @ref use_private_key_file
+        @see @ref set_password_callback
     */
     [[nodiscard]] std::error_code
     use_private_key(std::string_view private_key, tls_file_format format);
@@ -429,8 +429,8 @@ class BOOST_COROSIO_DECL tls_context
         @par Example
         @par !example use_private_key_file
 
-        @see use_private_key
-        @see set_password_callback
+        @see @ref use_private_key
+        @see @ref set_password_callback
     */
     [[nodiscard]] std::error_code
     use_private_key_file(std::string_view filename, tls_file_format format);
@@ -453,7 +453,7 @@ class BOOST_COROSIO_DECL tls_context
         @note Intermediate certificates inside the bundle are loaded and
             sent during the handshake on both backends.
 
-        @see use_pkcs12_file
+        @see @ref use_pkcs12_file
     */
     [[nodiscard]] std::error_code
     use_pkcs12(std::string_view data, std::string_view passphrase);
@@ -480,7 +480,7 @@ class BOOST_COROSIO_DECL tls_context
         @par Example
         @par !example use_pkcs12_file
 
-        @see use_pkcs12
+        @see @ref use_pkcs12
     */
     [[nodiscard]] std::error_code
     use_pkcs12_file(std::string_view filename, std::string_view passphrase);
@@ -503,8 +503,8 @@ class BOOST_COROSIO_DECL tls_context
             OpenSSL, any one does. WolfSSL skips certificates it cannot
             use and fails only when none load.
 
-        @see load_verify_file
-        @see set_default_verify_paths
+        @see @ref load_verify_file
+        @see @ref set_default_verify_paths
     */
     [[nodiscard]] std::error_code
     add_certificate_authority(std::string_view ca);
@@ -524,8 +524,8 @@ class BOOST_COROSIO_DECL tls_context
         @par Example
         @par !example load_verify_file
 
-        @see add_certificate_authority
-        @see add_verify_path
+        @see @ref add_certificate_authority
+        @see @ref add_verify_path
     */
     [[nodiscard]] std::error_code load_verify_file(std::string_view filename);
 
@@ -550,8 +550,8 @@ class BOOST_COROSIO_DECL tls_context
         @par Example
         @par !example add_verify_path
 
-        @see load_verify_file
-        @see set_default_verify_paths
+        @see @ref load_verify_file
+        @see @ref set_default_verify_paths
     */
     [[nodiscard]] std::error_code add_verify_path(std::string_view path);
 
@@ -582,9 +582,9 @@ class BOOST_COROSIO_DECL tls_context
         @par Example
         @par !example set_default_verify_paths
 
-        @see load_verify_file
-        @see add_verify_path
-        @see set_verify_mode
+        @see @ref load_verify_file
+        @see @ref add_verify_path
+        @see @ref set_verify_mode
     */
     [[nodiscard]] std::error_code set_default_verify_paths();
 
@@ -605,7 +605,7 @@ class BOOST_COROSIO_DECL tls_context
         @par Example
         @par !example set_min_protocol_version
 
-        @see set_max_protocol_version
+        @see @ref set_max_protocol_version
     */
     [[nodiscard]] std::error_code set_min_protocol_version(tls_version v);
 
@@ -624,7 +624,7 @@ class BOOST_COROSIO_DECL tls_context
         invalid window, where the minimum exceeds the maximum, yields a
         context that fails the handshake.
 
-        @see set_min_protocol_version
+        @see @ref set_min_protocol_version
     */
     [[nodiscard]] std::error_code set_max_protocol_version(tls_version v);
 
@@ -667,7 +667,7 @@ class BOOST_COROSIO_DECL tls_context
             single cipher list; this call and @ref set_ciphersuites are
             merged into one list.
 
-        @see set_ciphersuites
+        @see @ref set_ciphersuites
     */
     [[nodiscard]] std::error_code
     set_ciphersuites_tls13(std::string_view ciphers);
@@ -714,7 +714,7 @@ class BOOST_COROSIO_DECL tls_context
         @par Example
         @par !example set_verify_mode
 
-        @see tls_verify_mode
+        @see @ref tls_verify_mode
     */
     [[nodiscard]] std::error_code set_verify_mode(tls_verify_mode mode);
 
@@ -778,8 +778,8 @@ class BOOST_COROSIO_DECL tls_context
         @par Example
         @par !example set_verify_callback
 
-        @see verify_context
-        @see set_verify_mode
+        @see @ref verify_context
+        @see @ref set_verify_mode
     */
     template<typename Callback>
     void set_verify_callback(Callback callback);
@@ -804,7 +804,7 @@ class BOOST_COROSIO_DECL tls_context
             create separate contexts and select the appropriate one before
             creating the TLS stream.
 
-        @see tls_stream::set_hostname
+        @see @ref tls_stream::set_hostname
     */
     template<typename Callback>
     void set_servername_callback(Callback callback);
@@ -843,8 +843,8 @@ class BOOST_COROSIO_DECL tls_context
             other than `disabled` fails the handshake with
             `std::errc::function_not_supported`.
 
-        @see add_crl_file
-        @see set_revocation_policy
+        @see @ref add_crl_file
+        @see @ref set_revocation_policy
     */
     [[nodiscard]] std::error_code add_crl(std::string_view crl);
 
@@ -866,8 +866,8 @@ class BOOST_COROSIO_DECL tls_context
         @par Example
         @par !example add_crl_file
 
-        @see add_crl
-        @see set_revocation_policy
+        @see @ref add_crl
+        @see @ref set_revocation_policy
     */
     [[nodiscard]] std::error_code add_crl_file(std::string_view filename);
 
@@ -890,8 +890,8 @@ class BOOST_COROSIO_DECL tls_context
             build, else the handshake fails with
             `std::errc::function_not_supported`.
 
-        @see tls_revocation_policy
-        @see add_crl
+        @see @ref tls_revocation_policy
+        @see @ref add_crl
     */
     void set_revocation_policy(tls_revocation_policy policy);
 
@@ -915,7 +915,7 @@ class BOOST_COROSIO_DECL tls_context
         @par Example
         @par !example set_password_callback
 
-        @see tls_password_purpose
+        @see @ref tls_password_purpose
     */
     template<typename Callback>
     void set_password_callback(Callback callback);
diff --git a/include/boost/corosio/tls_stream.hpp b/include/boost/corosio/tls_stream.hpp
index b565fc70f..76da41fa5 100644
--- a/include/boost/corosio/tls_stream.hpp
+++ b/include/boost/corosio/tls_stream.hpp
@@ -79,7 +79,7 @@ make_owned_transport(S* p) noexcept
 
     Specifies whether to perform the TLS handshake as a client or server.
 
-    @see tls_stream::handshake
+    @see @ref tls_stream::handshake
 */
 enum class tls_role
 {
@@ -115,7 +115,7 @@ enum class tls_role
     `capy::strand`, or must otherwise never run concurrently. A
     single-threaded context needs no strand.
 
-    @see openssl_stream, wolfssl_stream
+    @see @ref openssl_stream, @ref wolfssl_stream
 */
 class BOOST_COROSIO_DECL tls_stream
 {
diff --git a/include/boost/corosio/wait_traits.hpp b/include/boost/corosio/wait_traits.hpp
index b923732b4..2a5610201 100644
--- a/include/boost/corosio/wait_traits.hpp
+++ b/include/boost/corosio/wait_traits.hpp
@@ -30,7 +30,7 @@ namespace boost::corosio {
 
     @tparam Clock The clock type whose durations are converted.
 
-    @see delay
+    @see @ref delay
 */
 template<class Clock>
 struct wait_traits
diff --git a/include/boost/corosio/win_object_handle.hpp b/include/boost/corosio/win_object_handle.hpp
index 06a993d4c..bafad2875 100644
--- a/include/boost/corosio/win_object_handle.hpp
+++ b/include/boost/corosio/win_object_handle.hpp
@@ -68,7 +68,7 @@ namespace boost::corosio {
     Distinct objects: Safe.@n
     Shared objects: Unsafe. One wait may be pending at a time.
 
-    @see win_stream_handle, timeout
+    @see @ref win_stream_handle, @ref timeout
 */
 class BOOST_COROSIO_DECL win_object_handle : public io_object
 {
@@ -218,7 +218,7 @@ class BOOST_COROSIO_DECL win_object_handle : public io_object
         Throws nothing. On failure the object is unchanged and @p h
         stays with the caller.
 
-        @see release
+        @see @ref release
     */
     [[nodiscard]] std::error_code assign(native_handle_type h) noexcept;
 
@@ -292,7 +292,7 @@ class BOOST_COROSIO_DECL win_object_handle : public io_object
         @par Example
         @par !example wait
 
-        @see timeout
+        @see @ref timeout
     */
     [[nodiscard]] wait_awaitable wait()
     {
diff --git a/include/boost/corosio/win_random_access_handle.hpp b/include/boost/corosio/win_random_access_handle.hpp
index 20a8f6961..f1a43f3b0 100644
--- a/include/boost/corosio/win_random_access_handle.hpp
+++ b/include/boost/corosio/win_random_access_handle.hpp
@@ -86,7 +86,7 @@ namespace boost::corosio {
     @par Example
     @par !example win_random_access_handle
 
-    @see random_access_file, win_stream_handle
+    @see @ref random_access_file, @ref win_stream_handle
 */
 class BOOST_COROSIO_DECL win_random_access_handle : public io_object
 {
@@ -310,7 +310,7 @@ class BOOST_COROSIO_DECL win_random_access_handle : public io_object
         Throws nothing. On failure the object is unchanged and @p h
         stays with the caller.
 
-        @see release
+        @see @ref release
     */
     [[nodiscard]] std::error_code assign(native_handle_type h) noexcept;
 
diff --git a/include/boost/corosio/win_stream_handle.hpp b/include/boost/corosio/win_stream_handle.hpp
index e23db370f..a838ec2b7 100644
--- a/include/boost/corosio/win_stream_handle.hpp
+++ b/include/boost/corosio/win_stream_handle.hpp
@@ -86,7 +86,7 @@ namespace boost::corosio {
     @par Example
     @par !example win_stream_handle
 
-    @see io_stream, stream_file, win_random_access_handle
+    @see @ref io_stream, @ref stream_file, @ref win_random_access_handle
 */
 class BOOST_COROSIO_DECL win_stream_handle : public io_stream
 {
@@ -198,7 +198,7 @@ class BOOST_COROSIO_DECL win_stream_handle : public io_stream
         Throws nothing. On failure the object is unchanged and @p h
         stays with the caller.
 
-        @see release
+        @see @ref release
     */
     [[nodiscard]] std::error_code assign(native_handle_type h) noexcept;
 
diff --git a/include/boost/corosio/wolfssl_stream.hpp b/include/boost/corosio/wolfssl_stream.hpp
index a2e1c52d5..1230b5eea 100644
--- a/include/boost/corosio/wolfssl_stream.hpp
+++ b/include/boost/corosio/wolfssl_stream.hpp
@@ -60,7 +60,7 @@ namespace boost::corosio {
     @par Example
     @par !example wolfssl_stream
 
-    @see tls_stream, openssl_stream
+    @see @ref tls_stream, @ref openssl_stream
 */
 class BOOST_COROSIO_DECL wolfssl_stream final : public tls_stream
 {
@@ -267,7 +267,7 @@ BOOST_COROSIO_DECL std::error_category const& wolfssl_category() noexcept;
     @return `true` if verify callbacks are fully supported by this build,
         `false` if installing one causes the handshake to fail.
 
-    @see tls_context::set_verify_callback
+    @see @ref tls_context::set_verify_callback
 */
 BOOST_COROSIO_DECL bool wolfssl_supports_verify_callback() noexcept;
 
@@ -281,7 +281,7 @@ BOOST_COROSIO_DECL bool wolfssl_supports_verify_callback() noexcept;
     @return `true` if ALPN is supported by this build, `false` if
         offering protocols causes the handshake to fail.
 
-    @see tls_context::set_alpn, tls_stream::alpn_protocol
+    @see @ref tls_context::set_alpn, @ref tls_stream::alpn_protocol
 */
 BOOST_COROSIO_DECL bool wolfssl_supports_alpn() noexcept;
 
@@ -294,7 +294,7 @@ BOOST_COROSIO_DECL bool wolfssl_supports_alpn() noexcept;
 
     @return `true` if revocation checking is supported by this build.
 
-    @see tls_context::add_crl, tls_context::set_revocation_policy
+    @see @ref tls_context::add_crl, @ref tls_context::set_revocation_policy
 */
 BOOST_COROSIO_DECL bool wolfssl_supports_crl() noexcept;
 
@@ -312,7 +312,7 @@ BOOST_COROSIO_DECL bool wolfssl_supports_crl() noexcept;
 
     @return `true` if IP-literal verification is supported by this build.
 
-    @see tls_stream::set_hostname
+    @see @ref tls_stream::set_hostname
 */
 BOOST_COROSIO_DECL bool wolfssl_supports_ip_alt_name() noexcept;