-
Notifications
You must be signed in to change notification settings - Fork 12.9k
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
Stabilize intra-doc links #74430
Merged
+107
−69
Merged
Stabilize intra-doc links #74430
Changes from 9 commits
Commits
Show all changes
11 commits
Select commit
Hold shift + click to select a range
c100e72
Stabilize intra-doc links
Manishearth 63d5bee
Move intra-doc-links documentation out of unstable section
Manishearth bc06674
Mention super/crate/self in docs
Manishearth f072e4a
Mention URL fragments
Manishearth 2a98409
Fill out docs on intra-doc resolution failure lint
Manishearth 4e0eb0b
Update src/doc/rustdoc/src/linking-to-items-by-name.md
Manishearth 175e305
Update src/doc/rustdoc/src/linking-to-items-by-name.md
Manishearth 51c1351
Resolve some conflicts
Manishearth 6f1fa2b
Fix lint name in docs
Manishearth 792b2ea
Update src/doc/rustdoc/src/lints.md
Manishearth 6928041
Update src/doc/rustdoc/src/linking-to-items-by-name.md
Manishearth File filter
Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
There are no files selected for viewing
This file contains 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
This file contains 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
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,65 @@ | ||
# Linking to items by name | ||
|
||
Rustdoc is capable of directly linking to other rustdoc pages in Markdown documentation using the path of item as a link. | ||
|
||
For example, in the following code all of the links will link to the rustdoc page for `Bar`: | ||
|
||
```rust | ||
/// This struct is not [Bar] | ||
pub struct Foo1; | ||
|
||
/// This struct is also not [bar](Bar) | ||
pub struct Foo2; | ||
|
||
/// This struct is also not [bar][b] | ||
/// | ||
/// [b]: Bar | ||
pub struct Foo3; | ||
|
||
/// This struct is also not [`Bar`] | ||
pub struct Foo4; | ||
|
||
pub struct Bar; | ||
``` | ||
|
||
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. Backticks around the link will be stripped. | ||
|
||
```rust,edition2018 | ||
use std::sync::mpsc::Receiver; | ||
|
||
/// This is an version of [`Receiver`], with support for [`std::future`]. | ||
/// | ||
/// You can obtain a [`std::future::Future`] by calling [`Self::recv()`]. | ||
pub struct AsyncReceiver<T> { | ||
sender: Receiver<T> | ||
} | ||
|
||
impl<T> AsyncReceiver<T> { | ||
pub async fn recv() -> T { | ||
unimplemented!() | ||
} | ||
} | ||
``` | ||
|
||
You can also link to sections using URL fragment specifiers: | ||
|
||
```rust | ||
/// This is a special implementation of [positional parameters] | ||
/// | ||
/// [positional parameters]: std::fmt#formatting-parameters | ||
struct MySpecialFormatter; | ||
``` | ||
|
||
Paths in Rust have three namespaces: type, value, and macro. Items from these namespaces are allowed to overlap. 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@`, `function@`, `mod@`, `fn@`, `module@`, `method@`, `prim@`, `primitive@`, `macro@`, or `derive@`:: | ||
Manishearth marked this conversation as resolved.
Show resolved
Hide resolved
|
||
|
||
```rust | ||
/// See also: [`Foo`](struct@Foo) | ||
struct Bar; | ||
|
||
/// This is different from [`Foo`](fn@Foo) | ||
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, as opposed to the module it is defined in. |
This file contains 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
This file contains 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
This file contains 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
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.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Maybe add a reminder explaining that before
#
it's the intra-doc and after it's an anchor in the target page.There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
I think it's pretty obvious here
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
It doesn't kill to add explanations and I had to read it twice to figure it out. So I think it totally deserves to have an extra explanation (better too much documentation than not enough 😛 ).
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
I actually think too much documentation can be a problem where it distracts from the important stuff, and I'd rather not explain how fragment specifiers work here.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
In this case, it's just a sentence. And originally, I just used
Type#anchor
to demonstrate it because using fully qualified path made the example more difficult to understand. I still think that we should add a sentence to explain quickly that after#
is the anchor to the target page.