Skip to content
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
merged 11 commits into from
Sep 24, 2020
1 change: 1 addition & 0 deletions src/doc/rustdoc/src/SUMMARY.md
Original file line number Diff line number Diff line change
Expand Up @@ -5,6 +5,7 @@
- [Command-line arguments](command-line-arguments.md)
- [The `#[doc]` attribute](the-doc-attribute.md)
- [Documentation tests](documentation-tests.md)
- [Linking to items by name](linking-to-items-by-name.md)
- [Lints](lints.md)
- [Passes](passes.md)
- [Advanced Features](advanced-features.md)
Expand Down
65 changes: 65 additions & 0 deletions src/doc/rustdoc/src/linking-to-items-by-name.md
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
Copy link
Member

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.

Copy link
Member Author

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

Copy link
Member

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 😛 ).

Copy link
Member Author

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.

Copy link
Member

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.

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@`:

```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.
43 changes: 39 additions & 4 deletions src/doc/rustdoc/src/lints.md
Original file line number Diff line number Diff line change
Expand Up @@ -13,18 +13,53 @@ Here is the list of the lints provided by `rustdoc`:

## broken_intra_doc_links

This lint **warns by default** and is **nightly-only**. This lint detects when
an intra-doc link fails to get resolved. For example:
This lint **warns by default**. This lint detects when an [intra-doc link] fails to get resolved. For example:

[intra-doc link]: linking-to-items-by-name.html

```rust
/// I want to link to [`Inexistent`] but it doesn't exist!
/// I want to link to [`Nonexistent`] but it doesn't exist!
pub fn foo() {}
```

You'll get a warning saying:

```text
error: `[`Inexistent`]` cannot be resolved, ignoring it...
warning: unresolved link to `Nonexistent`
--> test.rs:1:24
|
1 | /// I want to link to [`Nonexistent`] but it doesn't exist!
| ^^^^^^^^^^^^^ no item named `Nonexistent` in `test`
```

It will also warn when there is an ambiguity and suggest how to disambiguate:

```rust
/// [`Foo`]
pub fn function() {}

pub enum Foo {}

pub fn Foo(){}
```

```text
warning: `Foo` is both an enum and a function
--> test.rs:1:6
|
1 | /// [`Foo`]
| ^^^^^ ambiguous link
|
= note: `#[warn(broken_intra_doc_links)]` on by default
help: to link to the enum, prefix with the item type
|
1 | /// [`enum@Foo`]
| ^^^^^^^^^^
help: to link to the function, add parentheses
|
1 | /// [`Foo()`]
| ^^^^^^^

```

jyn514 marked this conversation as resolved.
Show resolved Hide resolved
## missing_docs
Expand Down
57 changes: 0 additions & 57 deletions src/doc/rustdoc/src/unstable-features.md
Original file line number Diff line number Diff line change
Expand Up @@ -38,63 +38,6 @@ future.
Attempting to use these error numbers on stable will result in the code sample being interpreted as
plain text.

### 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`. You may also use `foo()` and `foo!()` to refer to methods/functions and macros respectively.

```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!()
}
}
```

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@`:

```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.

## Extensions to the `#[doc]` attribute

These features operate by extending the `#[doc]` attribute, and thus can be caught by the compiler
Expand Down
10 changes: 2 additions & 8 deletions src/librustdoc/passes/collect_intra_doc_links.rs
Original file line number Diff line number Diff line change
Expand Up @@ -2,7 +2,6 @@ use rustc_ast as ast;
use rustc_data_structures::stable_set::FxHashSet;
use rustc_errors::{Applicability, DiagnosticBuilder};
use rustc_expand::base::SyntaxExtensionKind;
use rustc_feature::UnstableFeatures;
use rustc_hir as hir;
use rustc_hir::def::{
DefKind,
Expand Down Expand Up @@ -38,13 +37,8 @@ pub const COLLECT_INTRA_DOC_LINKS: Pass = Pass {
};

pub fn collect_intra_doc_links(krate: Crate, cx: &DocContext<'_>) -> Crate {
if !UnstableFeatures::from_environment().is_nightly_build() {
krate
} else {
let mut coll = LinkCollector::new(cx);

coll.fold_crate(krate)
}
let mut coll = LinkCollector::new(cx);
coll.fold_crate(krate)
}

enum ErrorKind<'a> {
Expand Down