Error about redundant_explicit_links with conditional no_std

[laurmaedje]

I tried this code:

//! [`String`][string]
//!
//! [string]: alloc::string::String

#![cfg_attr(not(feature = "std"), no_std)]

extern crate alloc;

[package]
name = "reproduction"
version = "0.1.0"
edition = "2021"

[features]
default = ["std"]
std = []

And then ran this command:

RUSTDOCFLAGS="-D warnings" cargo +nightly doc

I expected to see this happen: Documents without errors.

Instead, this happened: Error that link target is redundant. Only happens if std feature is enabled because String is in scope then. However, the explicit anchor is required for no_std.

error: redundant explicit link target
 --> src/lib.rs:1:16
  |
1 | //! [`String`][string]
  |      --------  ^^^^^^ explicit target is redundant
  |      |
  |      because label contains path that resolves to same destination

Perhaps, this is just an unfortunate situation where I need to use #![allow(rustdoc::redundant_explicit_links)], but it was confusing at first.

Meta

rustc --version --verbose:

rustc 1.74.0-nightly (e3abbd499 2023-09-06)
binary: rustc
commit-hash: e3abbd4994f72888f9e5e44dc89a4102e48c2a54
commit-date: 2023-09-06
host: aarch64-apple-darwin
release: 1.74.0-nightly
LLVM version: 17.0.0

[fmease]

cc @ChAoSUnItY (#113167)

[ChAoSUnItY]

It seems that the warning is true, since extern crate alloc by default will makes std crate not accessible, which makes doc link links to alloc::string::String by default.

Additionally, if this is not intentional, perhaps before you move on and makes extern crate alloc conditionally by feature, documenting something conditionally based on feature is probably not a good idea.

[laurmaedje]

It seems that the warning is true, since extern crate alloc by default will makes std crate not accessible

Perhaps I'm misunderstanding, but is this true? After all, this compiles fine:

extern crate alloc;

fn main() {
    let _ = std::string::String::new();
}

[ChAoSUnItY]

Try remove "std" feature from default faeture, after removal, you'll see something like this:

error[E0433]: failed to resolve: use of undeclared crate or module `std`
 --> src\main.rs:9:13
  |
9 |     let _ = std::string::String::new();
  |             ^^^ use of undeclared crate or module `std`
  |
help: consider importing this struct
  |
5 + use alloc::string::String;
  |
help: if you import `String`, refer to it directly
  |
9 -     let _ = std::string::String::new();
9 +     let _ = String::new();
  |

[laurmaedje]

Yeah sure, because of the no_std that is enabled via #![cfg_attr(not(feature = "std"), no_std)]. But String is not globally in scope with no_std. I could import it manually, but then rust would complain about an unused import. Therefore, I wanted to instead provide the full path in the docs link, since alloc::string::String always works.

[ChAoSUnItY]

After testing with few different approaches with the following code:

//! Unspecified: [`String`]
//! 
//! Std String: [`String`][std::string::String]
//! Alloc String: [`String`][alloc::string::String]
//! Std referenced String: [`String`][std_string]
//! Alloc referenced String: [`String`][alloc_string]
//! 
//! [std_string]: std::string::String
//! [alloc_string]: alloc::string::String

#![cfg_attr(not(feature = "std"), no_std)]

extern crate alloc;

fn main() {
}

All links link to alloc::string::String (yes, even explicit link std::string::String will also correct to alloc::string::String). I assume this issue is discussed in #3011, and probably not lint's problem.

[kadiwa4]

This issue is related to a newer issue about unused_imports: #121708.

The root cause of the issue is often that people conditionally depend on std like this:

#![cfg_attr(not(feature = "std"), no_std)]

Which will result in the std prelude sometimes being activated.
You can work around the warnings by instead doing this and not using the std prelude in your crate anymore:

#![no_std]

#[cfg(feature = "std")]
extern crate std;