79079978

Date: 2024-10-12 00:22:54
Score: 0.5
Natty:
Report link

While #[cfg(doc)] as @ChayimFriedman suggested works fine, I couldn't find a way to highlight unused imports for docs, which is e.g. needed when a documentation is updated later and the link is removed.

// doesn't warn about unused import, even if there is no link anymore

#[cfg(doc)]
use std::ops::Add;

/// documentation without link
pub fn foo() {}

Therefore, \\\ [Add](std::ops::Add), as suggested by @SilvioMayolo, seems to be more suitable long-term, even if it means more typing.

If you add a link with qualified path to your documentation, you don't get any warnings:

// generates no warnings

/// [Add](std::ops::Add)
pub fn foo() {}

If you forgot to add the path for a docs link where the import is missing (or if you later refactor your code and remove an import needed for a link), the rustdoc::broken_intra_doc_links lint has you covered and will warn about an unresolved link.

// warns about unresolved link

/// [Add]
pub fn foo() {}

If you later add an import that is already used in a link, the rustdoc::redundant_explicit_links lint has you covered and will warn you about a redundant explicit link target.

// warns about redundant explicit link target

use std::ops::Add;

/// [Add](std::ops::Add)
pub fn foo() {}

While both lints are warn-by-default, you can also make this explicit by adding the lints to your main.rs and/or lib.rs.

#![warn(rustdoc::broken_intra_doc_links)]
#![warn(rustdoc::redundant_explicit_links)]

You could also use deny() or forbid() instead of warn() to prevent your documentation from being created while there are linking errors.

Reasons:
  • Long answer (-1):
  • Has code block (-0.5):
  • User mentioned (1): @ChayimFriedman
  • User mentioned (0): @SilvioMayolo
  • Low reputation (1):
Posted by: Skru