From 02717911fd3fdbdd284c0c41f9a42af8dd1fe827 Mon Sep 17 00:00:00 2001 From: Joshua Nelson Date: Sun, 10 Jan 2021 08:42:51 -0500 Subject: [PATCH 1/7] Update intra-doc link documentation to match the implementation --- .../rustdoc/src/linking-to-items-by-name.md | 64 ++++++++++++++++--- 1 file changed, 56 insertions(+), 8 deletions(-) diff --git a/src/doc/rustdoc/src/linking-to-items-by-name.md b/src/doc/rustdoc/src/linking-to-items-by-name.md index 76e04398530fe..bdd6eecda6d32 100644 --- a/src/doc/rustdoc/src/linking-to-items-by-name.md +++ b/src/doc/rustdoc/src/linking-to-items-by-name.md @@ -1,7 +1,7 @@ # Linking to items by name Rustdoc is capable of directly linking to other rustdoc pages using the path of -the item as a link. +the item as a link. This is referred to as an 'intra-doc link'. For example, in the following code all of the links will link to the rustdoc page for `Bar`: @@ -27,8 +27,23 @@ pub struct Bar; Backticks around the link will be stripped, so ``[`Option`]`` will correctly link to `Option`. -You can refer to anything in scope, and use paths, including `Self`, `self`, -`super`, and `crate`. You may also use `foo()` and `foo!()` to refer to methods/functions and macros, respectively. +## Valid links + +You can refer to anything in scope, and use paths, including `Self`, `self`, `super`, and +`crate`. Associated items (functions, types, and constants) are supported, but [not for blanket +trait implementations][#79682]. Rustdoc also supports linking to the following primitives, which +have no path and cannot be imported: + +- [`slice`](https://doc.rust-lang.org/std/primitive.slice.html) +- [`array`](https://doc.rust-lang.org/std/primitive.array.html) +- [`tuple`](https://doc.rust-lang.org/std/primitive.tuple.html) +- [`unit`](https://doc.rust-lang.org/std/primitive.unit.html) +- [`fn`](https://doc.rust-lang.org/std/primitive.fn.html) +- [`pointer`](https://doc.rust-lang.org/std/primitive.pointer.html), `*`, `*const`, or `*mut` +- [`reference`](https://doc.rust-lang.org/std/primitive.reference.html), `&`, or `&mut` +- [`never`](https://doc.rust-lang.org/std/primitive.never.html) or `!` + +[#79682]: https://github.com/rust-lang/rust/pull/79682 You can also refer to items with generic parameters like `Vec`. The link will resolve as if you had written ``[`Vec`](Vec)``. Fully-qualified syntax (for example, @@ -53,7 +68,7 @@ impl AsyncReceiver { } ``` -You can also link to sections using URL fragment specifiers: +Rustdoc allows using URL fragment specifiers, just like a normal link: ```rust /// This is a special implementation of [positional parameters]. @@ -62,9 +77,13 @@ You can also link to sections using URL fragment specifiers: struct MySpecialFormatter; ``` -Paths in Rust have three namespaces: type, value, and macro. Item names must be -unique within their namespace, but can overlap with items outside of their -namespace. In case of ambiguity, rustdoc will warn about the ambiguity and ask you to disambiguate, which can be done by using a prefix like `struct@`, `enum@`, `type@`, `trait@`, `union@`, `const@`, `static@`, `value@`, `fn@`, `function@`, `mod@`, `module@`, `method@`, `prim@`, `primitive@`, `macro@`, or `derive@`: +## Namespaces and Disambiguators + +Paths in Rust have three namespaces: type, value, and macro. Item names must be unique within +their namespace, but can overlap with items outside of their namespace. In case of ambiguity, +rustdoc will warn about the ambiguity and ask you to disambiguate, which can be done by using a +prefix like `struct@`, `enum@`, `type@`, `trait@`, `union@`, `const@`, `static@`, `value@`, +`fn@`, `function@`, `mod@`, `module@`, `method@`, `prim@`, `primitive@`, `macro@`, or `derive@`: ```rust /// See also: [`Foo`](struct@Foo) @@ -76,6 +95,9 @@ struct Foo {} fn Foo() {} ``` +These prefixes will be stripped when displayed in the documentation, so `[struct@Foo]` +will be rendered as `Foo`. + You can also disambiguate for functions by adding `()` after the function name, or for macros by adding `!` after the macro name: @@ -89,6 +111,32 @@ struct Foo {} fn Foo() {} ``` -Note: Because of how `macro_rules!` macros are scoped in Rust, the intra-doc links of a `macro_rules!` macro will be resolved [relative to the crate root][#72243], as opposed to the module it is defined in. +## Warnings, re-exports, and scoping + +Links are resolved in the current module scope, even when re-exported. If a link from another +crate fails to resolve, no warning is given. + +When re-exporting an item, rustdoc allows additional documentation to it. That documentation will +be resolved in the new scope, not the original, allowing you to link to items in the current +crate. The new links will still give a warning if they fail to resolve. + +```rust +/// See also [foo()] +pub use std::process::Command; + +pub fn foo() {} +``` + +This is especially useful for proc-macros, which must always be in their own dedicated crate. + +Note: Because of how `macro_rules!` macros are scoped in Rust, the intra-doc links of a +`macro_rules!` macro will be resolved [relative to the crate root][#72243], as opposed to the +module it is defined in. + +If links do not look 'sufficiently like' an intra-doc link, they will be ignored and no warning +will be given, even if the link fails to resolve. For example, any link containing `/` or `[]` +characters will be ignored. You can see the full criteria for 'sufficiently like' in [the source +code]. [#72243]: https://github.com/rust-lang/rust/issues/72243 +[the source code]: https://github.com/rust-lang/rust/blob/34628e5b533d35840b61c5db0665cf7633ed3c5a/src/librustdoc/passes/collect_intra_doc_links.rs#L982 From d5392d1962208398a64a715698f05457840e6851 Mon Sep 17 00:00:00 2001 From: Joshua Nelson Date: Sun, 10 Jan 2021 10:15:15 -0500 Subject: [PATCH 2/7] Document differences from markdown --- src/doc/rustdoc/src/linking-to-items-by-name.md | 3 +++ 1 file changed, 3 insertions(+) diff --git a/src/doc/rustdoc/src/linking-to-items-by-name.md b/src/doc/rustdoc/src/linking-to-items-by-name.md index bdd6eecda6d32..1fab4bc6b9011 100644 --- a/src/doc/rustdoc/src/linking-to-items-by-name.md +++ b/src/doc/rustdoc/src/linking-to-items-by-name.md @@ -24,6 +24,9 @@ pub struct Foo4; pub struct Bar; ``` +Unlike normal markdown, `[bar][Bar]` syntax is also supported without needing a +`[Bar]: ...` reference link, and links are case-sensitive. + Backticks around the link will be stripped, so ``[`Option`]`` will correctly link to `Option`. From db0b4166564b235c29e6eaf371ad29330da7b851 Mon Sep 17 00:00:00 2001 From: Joshua Nelson Date: Sun, 10 Jan 2021 16:00:18 -0500 Subject: [PATCH 3/7] Address review comments - Improve wording - Use relative links - Use a proper list instead of a wall of text - Improve examples --- .../rustdoc/src/linking-to-items-by-name.md | 66 ++++++++++++------- 1 file changed, 41 insertions(+), 25 deletions(-) diff --git a/src/doc/rustdoc/src/linking-to-items-by-name.md b/src/doc/rustdoc/src/linking-to-items-by-name.md index 1fab4bc6b9011..1da54864a8ec9 100644 --- a/src/doc/rustdoc/src/linking-to-items-by-name.md +++ b/src/doc/rustdoc/src/linking-to-items-by-name.md @@ -24,7 +24,7 @@ pub struct Foo4; pub struct Bar; ``` -Unlike normal markdown, `[bar][Bar]` syntax is also supported without needing a +Unlike normal Markdown, `[bar][Bar]` syntax is also supported without needing a `[Bar]: ...` reference link, and links are case-sensitive. Backticks around the link will be stripped, so ``[`Option`]`` will correctly @@ -37,14 +37,14 @@ You can refer to anything in scope, and use paths, including `Self`, `self`, `su trait implementations][#79682]. Rustdoc also supports linking to the following primitives, which have no path and cannot be imported: -- [`slice`](https://doc.rust-lang.org/std/primitive.slice.html) -- [`array`](https://doc.rust-lang.org/std/primitive.array.html) -- [`tuple`](https://doc.rust-lang.org/std/primitive.tuple.html) -- [`unit`](https://doc.rust-lang.org/std/primitive.unit.html) -- [`fn`](https://doc.rust-lang.org/std/primitive.fn.html) -- [`pointer`](https://doc.rust-lang.org/std/primitive.pointer.html), `*`, `*const`, or `*mut` -- [`reference`](https://doc.rust-lang.org/std/primitive.reference.html), `&`, or `&mut` -- [`never`](https://doc.rust-lang.org/std/primitive.never.html) or `!` +- [`slice`](../../std/primitive.slice.html) +- [`array`](../../std/primitive.array.html) +- [`tuple`](../../std/primitive.tuple.html) +- [`unit`](../../std/primitive.unit.html) +- [`fn`](../../std/primitive.fn.html) +- [`pointer`](../../std/primitive.pointer.html), `*`, `*const`, or `*mut` +- [`reference`](../../std/primitive.reference.html), `&`, or `&mut` +- [`never`](../../std/primitive.never.html) or `!` [#79682]: https://github.com/rust-lang/rust/pull/79682 @@ -83,10 +83,8 @@ struct MySpecialFormatter; ## Namespaces and Disambiguators Paths in Rust have three namespaces: type, value, and macro. Item names must be unique within -their namespace, but can overlap with items outside of their namespace. In case of ambiguity, -rustdoc will warn about the ambiguity and ask you to disambiguate, which can be done by using a -prefix like `struct@`, `enum@`, `type@`, `trait@`, `union@`, `const@`, `static@`, `value@`, -`fn@`, `function@`, `mod@`, `module@`, `method@`, `prim@`, `primitive@`, `macro@`, or `derive@`: +their namespace, but can overlap with items in other namespaces. In case of ambiguity, +rustdoc will warn about the ambiguity and ask you to disambiguate. ```rust /// See also: [`Foo`](struct@Foo) @@ -98,6 +96,22 @@ struct Foo {} fn Foo() {} ``` +The following prefixes can be used: + +- `struct@` +- `enum@` +- `type@` +- `trait@` +- `union@` +- `const@` +- `static@` +- `value@` +- `fn@` / `function@` / `method@` +- `mod@` / `module@` +- `prim@` / `primitive@` +- `macro@` +- `derive@` + These prefixes will be stripped when displayed in the documentation, so `[struct@Foo]` will be rendered as `Foo`. @@ -105,23 +119,25 @@ You can also disambiguate for functions by adding `()` after the function name, or for macros by adding `!` after the macro name: ```rust -/// See also: [`Foo`](struct@Foo) -struct Bar; +/// This is different from [`foo!`] +fn foo() {} -/// This is different from [`Foo()`] -struct Foo {} - -fn Foo() {} +/// This is different from [`foo()`] +macro_rules! foo { + () => {} +} ``` ## Warnings, re-exports, and scoping -Links are resolved in the current module scope, even when re-exported. If a link from another -crate fails to resolve, no warning is given. +Links are resolved in the scope of the module where the item is defined, even +when the item is re-exported. If a link from another crate fails to resolve, no +warning is given. -When re-exporting an item, rustdoc allows additional documentation to it. That documentation will -be resolved in the new scope, not the original, allowing you to link to items in the current -crate. The new links will still give a warning if they fail to resolve. +When re-exporting an item, rustdoc allows adding additional documentation to it. +That additional documentation will be resolved in scope of the re-export, not +the original, allowing you to link to items in the new crate. The new links +will still give a warning if they fail to resolve. ```rust /// See also [foo()] @@ -130,7 +146,7 @@ pub use std::process::Command; pub fn foo() {} ``` -This is especially useful for proc-macros, which must always be in their own dedicated crate. +This is especially useful for proc-macros, which must always be defined in their own dedicated crate. Note: Because of how `macro_rules!` macros are scoped in Rust, the intra-doc links of a `macro_rules!` macro will be resolved [relative to the crate root][#72243], as opposed to the From 21717f0c172ed99aa398fbb2c4dcf059639bf98f Mon Sep 17 00:00:00 2001 From: Joshua Nelson Date: Sun, 10 Jan 2021 16:31:37 -0500 Subject: [PATCH 4/7] Fix typo Co-authored-by: Camelid --- src/doc/rustdoc/src/linking-to-items-by-name.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/doc/rustdoc/src/linking-to-items-by-name.md b/src/doc/rustdoc/src/linking-to-items-by-name.md index 1da54864a8ec9..eb7ef78a65964 100644 --- a/src/doc/rustdoc/src/linking-to-items-by-name.md +++ b/src/doc/rustdoc/src/linking-to-items-by-name.md @@ -135,7 +135,7 @@ when the item is re-exported. If a link from another crate fails to resolve, no warning is given. When re-exporting an item, rustdoc allows adding additional documentation to it. -That additional documentation will be resolved in scope of the re-export, not +That additional documentation will be resolved in the scope of the re-export, not the original, allowing you to link to items in the new crate. The new links will still give a warning if they fail to resolve. From 44c72f65d600aa1e76c0948ceb07cac9cf175e5e Mon Sep 17 00:00:00 2001 From: Joshua Nelson Date: Sun, 10 Jan 2021 23:10:05 -0500 Subject: [PATCH 5/7] Fix relative links Co-authored-by: Camelid --- src/doc/rustdoc/src/linking-to-items-by-name.md | 16 ++++++++-------- 1 file changed, 8 insertions(+), 8 deletions(-) diff --git a/src/doc/rustdoc/src/linking-to-items-by-name.md b/src/doc/rustdoc/src/linking-to-items-by-name.md index eb7ef78a65964..02390f658afee 100644 --- a/src/doc/rustdoc/src/linking-to-items-by-name.md +++ b/src/doc/rustdoc/src/linking-to-items-by-name.md @@ -37,14 +37,14 @@ You can refer to anything in scope, and use paths, including `Self`, `self`, `su trait implementations][#79682]. Rustdoc also supports linking to the following primitives, which have no path and cannot be imported: -- [`slice`](../../std/primitive.slice.html) -- [`array`](../../std/primitive.array.html) -- [`tuple`](../../std/primitive.tuple.html) -- [`unit`](../../std/primitive.unit.html) -- [`fn`](../../std/primitive.fn.html) -- [`pointer`](../../std/primitive.pointer.html), `*`, `*const`, or `*mut` -- [`reference`](../../std/primitive.reference.html), `&`, or `&mut` -- [`never`](../../std/primitive.never.html) or `!` +- [`slice`](../std/primitive.slice.html) +- [`array`](../std/primitive.array.html) +- [`tuple`](../std/primitive.tuple.html) +- [`unit`](../std/primitive.unit.html) +- [`fn`](../std/primitive.fn.html) +- [`pointer`](../std/primitive.pointer.html), `*`, `*const`, or `*mut` +- [`reference`](../std/primitive.reference.html), `&`, or `&mut` +- [`never`](../std/primitive.never.html) or `!` [#79682]: https://github.com/rust-lang/rust/pull/79682 From 86e2fcbf314f869670bf0f91836275987f61f686 Mon Sep 17 00:00:00 2001 From: Joshua Nelson Date: Thu, 11 Feb 2021 17:31:12 -0500 Subject: [PATCH 6/7] Don't include quite so much detail about the implementation --- .../rustdoc/src/linking-to-items-by-name.md | 50 ++++++------------- 1 file changed, 16 insertions(+), 34 deletions(-) diff --git a/src/doc/rustdoc/src/linking-to-items-by-name.md b/src/doc/rustdoc/src/linking-to-items-by-name.md index 02390f658afee..0ca280221787b 100644 --- a/src/doc/rustdoc/src/linking-to-items-by-name.md +++ b/src/doc/rustdoc/src/linking-to-items-by-name.md @@ -25,7 +25,7 @@ pub struct Bar; ``` Unlike normal Markdown, `[bar][Bar]` syntax is also supported without needing a -`[Bar]: ...` reference link, and links are case-sensitive. +`[Bar]: ...` reference link. Backticks around the link will be stripped, so ``[`Option`]`` will correctly link to `Option`. @@ -34,17 +34,8 @@ link to `Option`. You can refer to anything in scope, and use paths, including `Self`, `self`, `super`, and `crate`. Associated items (functions, types, and constants) are supported, but [not for blanket -trait implementations][#79682]. Rustdoc also supports linking to the following primitives, which -have no path and cannot be imported: - -- [`slice`](../std/primitive.slice.html) -- [`array`](../std/primitive.array.html) -- [`tuple`](../std/primitive.tuple.html) -- [`unit`](../std/primitive.unit.html) -- [`fn`](../std/primitive.fn.html) -- [`pointer`](../std/primitive.pointer.html), `*`, `*const`, or `*mut` -- [`reference`](../std/primitive.reference.html), `&`, or `&mut` -- [`never`](../std/primitive.never.html) or `!` +trait implementations][#79682]. Rustdoc also supports linking to all primitives listed in +[the standard library documentation](../std/index.html#primitives). [#79682]: https://github.com/rust-lang/rust/pull/79682 @@ -84,7 +75,7 @@ struct MySpecialFormatter; Paths in Rust have three namespaces: type, value, and macro. Item names must be unique within their namespace, but can overlap with items in other namespaces. In case of ambiguity, -rustdoc will warn about the ambiguity and ask you to disambiguate. +rustdoc will warn about the ambiguity and suggest a disambiguator. ```rust /// See also: [`Foo`](struct@Foo) @@ -96,24 +87,8 @@ struct Foo {} fn Foo() {} ``` -The following prefixes can be used: - -- `struct@` -- `enum@` -- `type@` -- `trait@` -- `union@` -- `const@` -- `static@` -- `value@` -- `fn@` / `function@` / `method@` -- `mod@` / `module@` -- `prim@` / `primitive@` -- `macro@` -- `derive@` - -These prefixes will be stripped when displayed in the documentation, so `[struct@Foo]` -will be rendered as `Foo`. +These prefixes will be stripped when displayed in the documentation, so `[struct@Foo]` will be +rendered as `Foo`. You can also disambiguate for functions by adding `()` after the function name, or for macros by adding `!` after the macro name: @@ -134,6 +109,15 @@ Links are resolved in the scope of the module where the item is defined, even when the item is re-exported. If a link from another crate fails to resolve, no warning is given. +```rust +mod inner { + /// Link to [f()] + pub struct S; + pub fn f() {} +} +pub use inner::S; // the link to `f` will still resolve correctly +``` + When re-exporting an item, rustdoc allows adding additional documentation to it. That additional documentation will be resolved in the scope of the re-export, not the original, allowing you to link to items in the new crate. The new links @@ -154,8 +138,6 @@ module it is defined in. If links do not look 'sufficiently like' an intra-doc link, they will be ignored and no warning will be given, even if the link fails to resolve. For example, any link containing `/` or `[]` -characters will be ignored. You can see the full criteria for 'sufficiently like' in [the source -code]. +characters will be ignored. [#72243]: https://github.com/rust-lang/rust/issues/72243 -[the source code]: https://github.com/rust-lang/rust/blob/34628e5b533d35840b61c5db0665cf7633ed3c5a/src/librustdoc/passes/collect_intra_doc_links.rs#L982 From c2694f15d05acd825883a992b390f54eda6f3696 Mon Sep 17 00:00:00 2001 From: Joshua Nelson Date: Mon, 22 Feb 2021 23:19:40 -0500 Subject: [PATCH 7/7] Fix compile failure due to 2015 module system being weird --- src/doc/rustdoc/src/linking-to-items-by-name.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/doc/rustdoc/src/linking-to-items-by-name.md b/src/doc/rustdoc/src/linking-to-items-by-name.md index 0ca280221787b..6ca1d1153b494 100644 --- a/src/doc/rustdoc/src/linking-to-items-by-name.md +++ b/src/doc/rustdoc/src/linking-to-items-by-name.md @@ -109,7 +109,7 @@ Links are resolved in the scope of the module where the item is defined, even when the item is re-exported. If a link from another crate fails to resolve, no warning is given. -```rust +```rust,edition2018 mod inner { /// Link to [f()] pub struct S;