This repository was archived by the owner on May 14, 2026. It is now read-only.
docs(guide/dev): intra-links#352
Merged
Merged
Conversation
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.
zkochan
approved these changes
Apr 30, 2026
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.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to subscribe to this conversation on GitHub.
Already have an account?
Sign in.
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
No description provided.