From ae94e989767b84177697b82fcaa1c8bb06d4e6e1 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Kh=E1=BA=A3i?= Date: Fri, 1 May 2026 01:34:50 +0700 Subject: [PATCH] docs(guide/dev): intra-links (#352) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit * docs(style): require intra-doc links for identifier mentions 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. * docs(style): tighten intra-doc link guidance Drop the redundant `//!` callout — saying "doc comment (`///` or `//!`)" once at the top is enough; the second example only restated the rule. --------- Co-authored-by: Claude --- pacquet/CODE_STYLE_GUIDE.md | 18 ++++++++++++++++++ 1 file changed, 18 insertions(+) diff --git a/pacquet/CODE_STYLE_GUIDE.md b/pacquet/CODE_STYLE_GUIDE.md index aebdbf452e..25839160e6 100644 --- a/pacquet/CODE_STYLE_GUIDE.md +++ b/pacquet/CODE_STYLE_GUIDE.md @@ -366,6 +366,24 @@ However, piping through any unary function **is** preferred when it continues an manifest.summarize().pipe(Some) ``` +### Doc comment intra-links + +When a doc comment (`/// ` or `//! `) mentions an identifier (type, trait, function, method, module, constant, macro, etc.) that is intra-linkable from the current scope, write the mention as a [rustdoc intra-doc link][intra-doc-links] rather than as bare prose. Intra-doc links give readers one-click navigation and let rustdoc warn when a referenced item is renamed or removed, so the docs stay in sync with the code. + +[intra-doc-links]: https://doc.rust-lang.org/rustdoc/write-documentation/linking-to-items-by-name.html + +```rust +// Good +/// Installs the package described by [`PackageManifest`] into [`Store`]. +pub fn install(manifest: &PackageManifest, store: &Store) { /* ... */ } + +// Bad: identifiers are mentioned as bare prose +/// Installs the package described by `PackageManifest` into `Store`. +pub fn install(manifest: &PackageManifest, store: &Store) { /* ... */ } +``` + +If the identifier is not directly in scope, use a path link (`` [`crate::store::Store`] ``) or a disambiguated link (`` [`Store`](crate::store::Store) ``) rather than dropping back to bare prose. Reserve plain backticks for things that genuinely cannot be linked, such as identifiers from external code that rustdoc cannot resolve, shell commands, file paths, or literal values. + ### Error Handling - Use `derive_more` for error types. Only derive the traits that are actually used: