Skip to content
This repository was archived by the owner on May 14, 2026. It is now read-only.

docs(guide/dev): intra-links#352

Merged
zkochan merged 2 commits into
mainfrom
claude/add-intra-linking-guidance-Y6Rma
Apr 30, 2026
Merged

docs(guide/dev): intra-links#352
zkochan merged 2 commits into
mainfrom
claude/add-intra-linking-guidance-Y6Rma

Conversation

@KSXGitHub

Copy link
Copy Markdown
Contributor

No description provided.

claude added 2 commits April 30, 2026 18:10
Add a CODE_STYLE_GUIDE.md section telling contributors (and AI agents)
to turn identifier mentions inside `///` and `//!` doc comments into
rustdoc intra-doc links when the identifier is reachable from scope.
Intra-links give readers one-click navigation and let rustdoc surface
broken-link warnings when items are renamed or removed.
Drop the redundant `//!` callout — saying "doc comment (`///` or `//!`)"
once at the top is enough; the second example only restated the rule.
@KSXGitHub KSXGitHub requested a review from zkochan April 30, 2026 18:15
@KSXGitHub KSXGitHub marked this pull request as ready for review April 30, 2026 18:16
@zkochan zkochan merged commit 2cfa384 into main Apr 30, 2026
@zkochan zkochan deleted the claude/add-intra-linking-guidance-Y6Rma branch April 30, 2026 18:34
KSXGitHub pushed a commit that referenced this pull request Apr 30, 2026
After merging main (which brought in PR #352's "Doc comment intra-links"
guide and PR #351's "Documentation comments / private item refs" guide),
re-audit the bin-linking docs against the new sections and convert two
remaining bare-prose item mentions:

* `crates/cmd-shim/src/capabilities.rs:23` — the `FsReadHead` trait doc
  said "via `read_head_filled`" with the helper's name as bare prose.
  Convert to [`crate::read_head_filled`].
* `crates/package-manager/src/link_bins.rs:69` — the `LinkVirtualStoreBins`
  struct doc named `create_symlink_layout` as bare prose. The function
  shares its name with the module that hosts it, so the link needs to
  disambiguate; use `[create_symlink_layout](crate::create_symlink_layout())`
  to point at the function form.

The `Command` mention in `bin_resolver.rs:9` deliberately stays as bare
backticks: it refers to *upstream pnpm's* `Command` class (in
`@pnpm/bins.resolver`), not the local struct, so the bare-prose form is
the accurate reading.
KSXGitHub pushed a commit that referenced this pull request Apr 30, 2026
…links

Apply the convention added by #352: when a doc comment
mentions an identifier that is rustdoc-linkable from the current scope,
write it as an intra-doc link rather than bare backticks. Two callouts
in `crates/modules-yaml/src/lib.rs` qualify (`serde_json::to_string_pretty`
and `serde_json::Value`); both are public re-exports of in-tree
dependencies, so rustdoc can resolve them and a renamed/removed item
will surface as a `cargo doc` warning instead of stale prose.

`cargo doc --no-deps` runs clean with `-D
rustdoc::broken_intra_doc_links -D rustdoc::private_intra_doc_links`,
confirming no `///` doc references a more-private item per the
guidance in #351.
KSXGitHub pushed a commit that referenced this pull request Apr 30, 2026
Follow the new style rules from #352 (use rustdoc intra-doc links
for in-scope identifiers in doc comments) across the auth-related
files added by this PR.

Notable fixes:
* `crates/npmrc/src/env_replace.rs` had a non-resolving
  `[\`EnvReplaceError::Missing\`]` reference (`EnvReplaceError` is a
  struct, not an enum). Drop the bogus `::Missing` segment and link
  the type itself.
* Test docstrings across `auth.rs`, `npmrc_auth.rs`, and `lib.rs`
  now use intra-doc links for the in-scope items they reference
  (`nerf_dart`, `ParsedUrl::parse`, `creds_to_header`,
  `split_creds_key`, `apply_creds_field`, `NpmrcAuth::*`,
  `Npmrc::current`, `EnvVar::var`, `env_replace`, etc.).
* Registry test docstrings link `Package::fetch_from_registry` and
  `PackageVersion::fetch_from_registry` rather than naming them in
  bare backticks.

PR 351 ("don't reference private items from public docs") audited
in the same pass; the new pub items in this PR only reference other
pub items in their docs, so no changes were needed for that rule.
The integration test in `crates/cli/tests/install.rs` keeps bare
backticks because rustdoc does not process integration-test files
and the imported scope there does not include the referenced
`pacquet_npmrc` items.
KSXGitHub pushed a commit that referenced this pull request Apr 30, 2026
After merging main (which brought in PR #352's "Doc comment intra-links"
guide and PR #351's "Documentation comments / private item refs" guide),
re-audit the bin-linking docs against the new sections and convert two
remaining bare-prose item mentions:

* `crates/cmd-shim/src/capabilities.rs:23` — the `FsReadHead` trait doc
  said "via `read_head_filled`" with the helper's name as bare prose.
  Convert to [`crate::read_head_filled`].
* `crates/package-manager/src/link_bins.rs:69` — the `LinkVirtualStoreBins`
  struct doc named `create_symlink_layout` as bare prose. The function
  shares its name with the module that hosts it, so the link needs to
  disambiguate; use `[create_symlink_layout](crate::create_symlink_layout())`
  to point at the function form.

The `Command` mention in `bin_resolver.rs:9` deliberately stays as bare
backticks: it refers to *upstream pnpm's* `Command` class (in
`@pnpm/bins.resolver`), not the local struct, so the bare-prose form is
the accurate reading.
Sign up for free to subscribe to this conversation on GitHub. Already have an account? Sign in.

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

3 participants