# iter rustdoc-sweep — clear all 23 cargo-doc warnings

**Date:** 2026-05-13
**Started from:** 48b1f77 (post-WhatsNew str-concat done-state)
**Status:** DONE

## Summary

Hygiene sweep against `cargo doc --workspace --no-deps`. Before: 23
warnings (17 in `ailang-check` + 4 in `ailang-core` + 2 in
`ailang-surface`). After: zero. All edits are documentation-only —
no production code, no test code changed. Tests stay 562 green.

Two warning classes, fixed with two different shapes:

- **Public doc links to private items** (15 warnings). Pattern:
  a `pub` item's `///` doc references `[`fn_name`]` where `fn_name`
  is `pub(crate)` or private. Fix: replace ``[`fn_name`]`` with
  the plain backtick-code-span ``` `fn_name` ```. The identifier
  stays readable in rendered docs but rustdoc no longer tries to
  resolve the link.
- **Unresolved links** (8 warnings). Sub-classes:
  - ``[`Registry`]`` in `mono.rs` (×3) — `Registry` lives in
    `ailang_core::workspace` and the path was bare. Fixed by
    fully-qualifying as `[`ailang_core::workspace::Registry`]` /
    `[`ailang_core::workspace::Registry::entries`]`.
  - ``[`Env::class_methods`]`` — `Env` is in this crate but
    bare; the doc string was demoted to plain backticks
    (`` `crate::Env::class_methods` ``) because `Env` itself has
    no `pub` re-export at the crate root that rustdoc could
    follow.
  - ``[`crate::parse`]`` ambiguous in `loader.rs` (×2) — rustdoc
    saw both a function and a module with that path. Disambiguated
    to the function form via ``[`crate::parse()`]`` per
    rustdoc's own suggestion.
  - `metas[i]` in `lib.rs` — rustdoc parsed `[i]` as a link.
    Escaped as `metas\[i\]` (same fix for the sibling `vars\[i\]`).

## Files touched

- `crates/ailang-core/src/desugar.rs` (1 line)
- `crates/ailang-core/src/workspace.rs` (3 lines)
- `crates/ailang-surface/src/loader.rs` (2 lines)
- `crates/ailang-check/src/uniqueness.rs` (2 lines)
- `crates/ailang-check/src/diagnostic.rs` (1 line)
- `crates/ailang-check/src/mono.rs` (5 lines)
- `crates/ailang-check/src/lib.rs` (8 lines)

## Verification

- `cargo doc --workspace --no-deps 2>&1 | grep "^warning:" | wc -l`
  → `0`.
- `cargo test --workspace` → 562 passed, 0 failed (baseline holds).

## Concerns

- (none)

## Known debt

- (none)