git ents: treewide: fix all 47 rustdoc warnings for the phase-9 doc gate

commit bf9ca83

treewide: fix all 47 rustdoc warnings for the phase-9 doc gate

Demote intra-doc links to private items to plain code spans and repair two unresolved links, leaving cargo doc --no-deps warning-free.

Assisted-by: Claude:claude-sonnet-5

Joseph D. Carpinelli · 1 month ago

tree browse at HEAD · parents: 6e4c4b2 · comment on this commit

Reviews

No reviews of this commit yet — record a verdict below.

Start a review

crates/cli/ents-web/src/identity.rs @@ -69,7 +69,7 @@ /// signer's member when `--member` is omitted. fn public_openssh(&self) -> String; - /// This identity's display label for [`crate::pages::layout`]'s + /// This identity's display label for `crate::pages::layout`'s /// `.id-chip` (`roots.web-signing`) -- the one place this crate names /// "who is acting" for a human reader, as opposed to [`Self::actor`]'s /// commit-authorship signature.

crates/kernel/ents-model/src/lib.rs @@ -7,7 +7,7 @@ //! `ents-anchor`, `ents-sync`, and `ents-web` all depend on `ents-model` //! directly, and nothing here depends back on any of them. That is a //! deliberate constraint, not an oversight — see [`Effect::trigger`] and -//! [`Comment::anchor`] for the two places a richer type would +//! `Comment::anchor` (in `ents-forge`) for the two places a richer type would //! have been the natural choice and was rejected specifically to keep this //! edge one-directional. //!

crates/kiln/ents-kiln/src/lib.rs @@ -32,7 +32,7 @@ //! `&[(String, PathBuf)]` slice; resolving an effect's declared names to //! that slice is this crate's job, done by a composition root before it //! calls into `ents-effect`'s run loop. -//! - `meta-ref.typed-tree` — [`toolchain::entity`]'s round-trip test (see +//! - `meta-ref.typed-tree` — `toolchain::entity`'s round-trip test (see //! the module itself for the concrete test, folded into `toolchain`'s //! private `entity` submodule). //!

crates/cli/ents-web/src/pages/comments.rs @@ -6,13 +6,13 @@ //! already returns structured data for, rather than a bare reflected //! field list. //! -//! [`for_path`]/[`comment_card`]/[`comments_section`] are this module's +//! `for_path`/`comment_card`/`comments_section` are this module's //! second entry point: `crate::pages::files`'s blob view calls them to //! render the comments anchored to the file it is showing -- inline, //! interleaved at the anchored line, or in a below-the-blob section for //! one with no current line to interleave at -- rather than duplicating //! this module's own read-project-render pattern or its card markup. -//! [`for_commit`] is a third: `crate::pages::commits::show`'s own +//! `for_commit` is a third: `crate::pages::commits::show`'s own //! "conversation" section, listing every comment whose anchor was captured //! against that exact commit (`Anchor::commit`, not a projection onto any //! revision -- a commit page shows what was written about that commit, @@ -112,7 +112,7 @@ /// `GET /comments/{id}?rev=...`: the comment's body, its anchor, and the /// projection of that anchor onto `rev` (`anchor.projection`). Its state /// (`model.comment-state`) and the reply/resolve/reopen actions -/// ([`action_forms`], `model.comment-thread`, `model.comment-state`) render +/// (`action_forms`, `model.comment-thread`, `model.comment-state`) render /// alongside, so a comment is a conversation from its own page and not only /// from an issue's or a review's. ///

crates/cli/ents-web/src/pages/commits.rs @@ -1,6 +1,6 @@ //! `GET /commits`, `GET /commit/{oid}`: a read-only commit history and //! per-commit unified diff over `HEAD` -- a view of the code, not a tab of -//! its own (both routes render with [`super::Tab::Files`] active; see +//! its own (both routes render with `super::Tab::Files` active; see //! [`super`]'s own doc), reached from [`super::files`]'s "history" link. //! //! Reads go through `gix`'s high-level `Repository`/`Commit`/`Tree` types, @@ -13,13 +13,13 @@ //! [`gix::diff::blob::diff_with_slider_heuristics`] computes the hunks, and //! [`gix::diff::blob::unified_diff::ConsumeBinaryHunk`] renders them as the //! same textual unified-diff format `git diff` itself produces, which -//! [`diff_class`] then colorizes line by line -- no new dependency, since +//! `diff_class` then colorizes line by line -- no new dependency, since //! `gix`'s default features already enable `blob-diff`. //! //! `GET /commit/{oid}` also lists a "conversation": every comment whose //! anchor was captured against that exact commit //! (`crate::pages::comments::for_commit`), rendered below the diff via the -//! same [`crate::pages::comments::comment_card`] a blob view uses, each +//! same `crate::pages::comments::comment_card` a blob view uses, each //! naming its `path#lines` and linking into `crate::pages::files`'s own //! `#L<n>` gutter. A "comment on this commit" link beside the parents list //! reaches `crate::pages::comments::list`'s add form with `rev` prefilled

crates/cli/ents-web/src/pages/files.rs @@ -1,11 +1,11 @@ //! `GET /files`, `GET /files/{*path}`: a read-only directory listing and //! blob viewer over the `HEAD` tree of the repository `git ents serve` is -//! serving. A `.md` blob renders via [`crate::markdown`], a -//! `.adoc`/`.asciidoc`/`.asc`/`.adc` blob via [`crate::asciidoc`], and +//! serving. A `.md` blob renders via `crate::markdown`, a +//! `.adoc`/`.asciidoc`/`.asc`/`.adc` blob via `crate::asciidoc`, and //! everything else as a line-numbered source view, syntax-highlighted via //! [`arborium`] when its filename maps to a known grammar (ported from //! `pre-redo:crates/git-ents-server/src/web/pages.rs`'s own `highlight`; -//! see [`highlight`]'s own doc), escaped plain text otherwise. +//! see `highlight`'s own doc), escaped plain text otherwise. //! //! Tree/blob reads go through `gix`'s high-level `Repository`/`Tree`/`Blob` //! types (`repo.head_tree()`, `Tree::lookup_entry_by_path`, @@ -17,9 +17,9 @@ //! structured meta-ref data; browsing arbitrary repository content is not //! that). //! -//! [`crumbs`] renders only the path trail now -- every action that used to +//! `crumbs` renders only the path trail now -- every action that used to //! live at its trailing edge (jump into history, jump to the first -//! comment, add a comment) moved into [`blob_header`]'s own right-aligned +//! comment, add a comment) moved into `blob_header`'s own right-aligned //! action group, rendered above every blob view regardless of how it //! renders (raw source, a rendered document, or a binary placeholder); a //! directory listing carries neither the actions nor a header, since a @@ -30,10 +30,10 @@ //! rendered document or a binary placeholder) interleaves each comment's //! card directly after the row naming its anchored range's last line, //! full width across the blob's line-number and code columns -//! ([`source_view`]); a comment with no current line range (a whole-file +//! (`source_view`); a comment with no current line range (a whole-file //! anchor, or `ents_anchor::Projection::Outdated`) has nowhere to //! interleave, and renders in a below-the-blob "outdated comments" -//! section instead ([`outdated_comments_section`]). Doc-rendered and +//! section instead (`outdated_comments_section`). Doc-rendered and //! binary views keep every comment below the blob, unconditionally //! (`crate::pages::comments::comments_section`), since there is no source //! line to interleave at. @@ -45,9 +45,9 @@ //! exact commit being viewed) so a click on a gutter line number can select //! a line or a shift-extended range and open an inline comment composer //! cloned from a server-rendered `<template id="composer-template">` -//! ([`composer_template`]) -- with JS disabled the page stays fully usable -//! via [`blob_header`]'s "comment on this file" link and the plain `#L<n>` -//! anchors [`crate::pages::comments::comment_card`] already emits. +//! (`composer_template`) -- with JS disabled the page stays fully usable +//! via `blob_header`'s "comment on this file" link and the plain `#L<n>` +//! anchors `crate::pages::comments::comment_card` already emits. use std::sync::Arc;

crates/cli/ents-web/src/pages/meta.rs @@ -1,5 +1,5 @@ //! `GET /meta`: the landing page for the `meta` tab -- a card listing -//! every page family in [`super::META_SECTIONS`] with its blurb, so the +//! every page family in `super::META_SECTIONS` with its blurb, so the //! tab resolves to something other than an arbitrary pick of its five //! children. The rail those children render beside their own content //! (`super::layout_meta`) is this same table; this page is its index.

crates/cli/ents-web/src/pages/mod.rs @@ -11,12 +11,12 @@ //! and issue threads all need domain-specific rendering no generic //! reflection walk should grow special cases for). [`issues`], [`members`], //! [`effects`], [`toolchains`], [`redactions`], and [`inbox`] additionally -//! share one `meta` tab and [`META_SECTIONS`] rail rather than each carrying -//! its own top-level tab (see [`Tab`]'s own doc); [`meta`] is that group's +//! share one `meta` tab and `META_SECTIONS` rail rather than each carrying +//! its own top-level tab (see `Tab`'s own doc); [`meta`] is that group's //! `GET /meta` landing page. [`commits`] is a view of the code, not a tab of its own -- both -//! its routes render with [`Tab::Files`] active, reached from +//! its routes render with `Tab::Files` active, reached from //! [`files`]'s own "history" link. [`search`] renders with no tab active -//! at all, like [`account`]; it is reached from [`layout`]'s own nav +//! at all, like [`account`]; it is reached from `layout`'s own nav //! search form rather than any tab. pub mod account;

crates/cli/ents-web/src/pages/search.rs @@ -1,9 +1,9 @@ -//! `GET /search`: [`super::layout`]'s nav search form's target -- a plain +//! `GET /search`: `super::layout`'s nav search form's target -- a plain //! request-time substring scan over the served repository, deliberately //! with no index and no new state (a design decision this crate settled //! on rather than relitigated here): every request re-walks the `HEAD` //! tree and the meta-ref listings the pages that already own them use. -//! Renders with no tab active at all ([`super::Tab::None`]), like +//! Renders with no tab active at all (`super::Tab::None`), like //! [`super::account`], since it is reached from the nav search form //! rather than any tab.

crates/cli/git-ents/src/commands/issue.rs @@ -38,7 +38,7 @@ } /// `git ents issue new`: create an issue. When `title` is `None`, composes -/// the title and body interactively (see [`compose_in_editor`]). +/// the title and body interactively (see `compose_in_editor`). /// /// # Errors ///

crates/cli/git-ents/src/commands/serve.rs @@ -18,7 +18,7 @@ //! `user.signingkey`, else the default `~/.ssh/id_ed25519`) — no //! server-key indirection exists anywhere in this module, which is //! exactly what keeps `roots.web-signing`'s hosted-only indirection from -//! leaking into the local root. [`LocalIdentity::label`] additionally +//! leaking into the local root. `LocalIdentity::label` additionally //! resolves the signer's own enrolled member (reusing //! `crate::commands::members::find_by_key`, the same key-match loop //! `git ents members check` runs), so the web shell's identity chip shows

crates/forge/ents-forge/src/comment/mod.rs @@ -1,6 +1,6 @@ -//! The comment sub-domain: the [`Comment`] entity ([`entity`]), the -//! `comment` command's business logic ([`command`]), and the `comment` -//! subcommand's argument grammar ([`cli`]), kept in separate files so +//! The comment sub-domain: the [`Comment`] entity (`entity`), the +//! `comment` command's business logic (`command`), and the `comment` +//! subcommand's argument grammar (`cli`), kept in separate files so //! the data shape, the command mechanism, and the CLI grammar stay easy //! to read independently.

crates/forge/ents-forge/src/issue/mod.rs @@ -1,6 +1,6 @@ -//! The issue sub-domain: the [`Issue`] entity ([`entity`]), the `issue` -//! command's business logic ([`command`]), and the `issue` subcommand's -//! argument grammar ([`cli`]) — the same three-file split +//! The issue sub-domain: the [`Issue`] entity (`entity`), the `issue` +//! command's business logic (`command`), and the `issue` subcommand's +//! argument grammar (`cli`) — the same three-file split //! [`crate::comment`] and [`crate::review`] use, for the same reason: the //! data shape, the command mechanism, and the CLI grammar stay easy to //! read independently.

crates/forge/ents-forge/src/review/mod.rs @@ -1,6 +1,6 @@ -//! The review sub-domain: the [`Review`] entity ([`entity`]), the `review` -//! command's business logic ([`command`]), and the `review` subcommand's -//! argument grammar ([`cli`]) — the same three-file split +//! The review sub-domain: the [`Review`] entity (`entity`), the `review` +//! command's business logic (`command`), and the `review` subcommand's +//! argument grammar (`cli`) — the same three-file split //! [`crate::comment`] uses, for the same reason: the data shape, the //! command mechanism, and the CLI grammar stay easy to read independently.

crates/kiln/ents-kiln/src/toolchain/mod.rs @@ -1,7 +1,7 @@ -//! The toolchain sub-domain: the [`Toolchain`] entity ([`entity`]), its +//! The toolchain sub-domain: the [`Toolchain`] entity (`entity`), its //! resolution/materialization machinery ([`resolve`]), the `toolchain` -//! command's business logic ([`command`]), and the `toolchain` -//! subcommand's argument grammar ([`cli`]), kept in separate files so +//! command's business logic (`command`), and the `toolchain` +//! subcommand's argument grammar (`cli`), kept in separate files so //! the data shape, the resolution algorithm, the command mechanism, and //! the CLI grammar stay easy to read independently — the same split //! `ents-forge`'s `comment` sub-domain uses.