Rollup merge of rust-lang#74430 - Manishearth:stabilize-intra-doc, r=…

…Manishearth

Stabilize intra-doc links

Fixes rust-lang#43466

Thanks to the great work of @jyn514 in getting the [cross-crate reexport issue](rust-lang#65983) in intra-rustdoc links fixed, I think we're now in a position to stabilize this feature.

The tracking issue currently has two unresolved issues:

 - <s>behavior around doc(hidden): This is fixed in rust-lang#73365, which is just waiting for CI and should land tomorrow. It's also a pretty niche bug so while I expect it to land soon I don't think we need to block stabilization on it anyway.</s>
 - Non-identifier primitive types like slices: This was not a part of the original RFC anyway, and is a pretty niche use case

The feature itself, sans rust-lang#65983, has been shipped on nightly for three years now, with people using it on docs.rs. rust-lang#65983 itself is not an overwhelmingly central bit of functionality; the reason we elected to block stabilization on it was that back in 2017 it was not possible to fix the issue without some major refactorings of resolve, and we did not want to stabilize something that had such a potentially unfixable bug.

Given that we've fixed it, I see no reason to delay stabilization on this long awaited feature. It's possible that the latest patches have problems, however we _have_ done crater runs of some of the crucial parts. Furthermore, that's what the release trains are for, we will have a solid three months to let it ride the trains before it actually hits the stable compiler.

r? @rust-lang/rustdoc

src/doc/rustdoc/src/SUMMARY.md

@@ -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)

src/doc/rustdoc/src/linking-to-items-by-name.md

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

src/doc/rustdoc/src/lints.md

@@ -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()`]
+  |      ^^^^^^^
+
 ```
 
 ## missing_docs

src/doc/rustdoc/src/unstable-features.md

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

src/librustdoc/passes/collect_intra_doc_links.rs

@@ -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,
@@ -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> {