clippy::doc_markdown: item in documentation is missing backticks

warning: item in documentation is missing backticks
 --> main.rs:3:27
  |
3 | /// Do something with the foo_bar parameter. See also
  |                           ^^^^^^^
  |
  = help: for further information visit https://rust-lang.github.io/rust-clippy/stable/index.html#doc_markdown
  = note: `-W clippy::doc-markdown` implied by `-W clippy::pedantic`
help: try
  |
3 - /// Do something with the foo_bar parameter. See also
3 + /// Do something with the `foo_bar` parameter. See also
  |

/// Do something with the foo_bar parameter. See also
/// that::other::module::foo.
// ^ `foo_bar` and `that::other::module::foo` should be ticked.
fn doit(foo_bar: usize) {}

// Link text with `[]` brackets should be written as following:
/// Consume the array and return the inner
/// [`SmallVec<[T; INLINE_CAPACITY]>`][SmallVec].
/// [SmallVec]: SmallVec
fn main() {}

[lints.clippy]
doc_markdown = "warn"

#![warn(clippy::doc_markdown)]

cargo clippy -- -W clippy::doc-markdown

Clippy's own documentation

What it does

Checks for the presence of _, :: or camel-case words outside ticks in documentation.

Why is this bad?

Rustdoc supports markdown formatting, _, :: and camel-case probably indicates some code which should be included between ticks. _ can also be used for emphasis in markdown, this lint tries to consider that.

Known problems

Lots of bad docs won’t be fixed, what the lint checks for is limited, and there are still false positives. HTML elements and their content are not linted.

In addition, when writing documentation comments, including [] brackets inside a link text would trip the parser. Therefore, documenting link with [SmallVec<[T; INLINE_CAPACITY]>] and then [SmallVec<[T; INLINE_CAPACITY]>]: SmallVec would fail.

Examples

/// Do something with the foo_bar parameter. See also
/// that::other::module::foo.
// ^ `foo_bar` and `that::other::module::foo` should be ticked.
fn doit(foo_bar: usize) {}

// Link text with `[]` brackets should be written as following:
/// Consume the array and return the inner
/// [`SmallVec<[T; INLINE_CAPACITY]>`][SmallVec].
/// [SmallVec]: SmallVec
fn main() {}

Configuration

• doc-valid-idents: The list of words this lint should not consider as identifiers needing ticks. The value ".." can be used as part of the list to indicate that the configured values should be appended to the default configuration of Clippy. By default, any configuration will replace the default value. For example:

• doc-valid-idents = ["ClipPy"] would replace the default list with ["ClipPy"].

• doc-valid-idents = ["ClipPy", ".."] would append ClipPy to the default list.

  (default: ["KiB", "MiB", "GiB", "TiB", "PiB", "EiB", "MHz", "GHz", "THz", "AccessKit", "CoAP", "CoreFoundation", "CoreGraphics", "CoreText", "DevOps", "Direct2D", "Direct3D", "DirectWrite", "DirectX", "ECMAScript", "GPLv2", "GPLv3", "GitHub", "GitLab", "IPv4", "IPv6", "InfiniBand", "RoCE", "ClojureScript", "CoffeeScript", "JavaScript", "PostScript", "PureScript", "TypeScript", "PowerPC", "PowerShell", "WebAssembly", "NaN", "NaNs", "OAuth", "GraphQL", "SQLite", "MySQL", "PostgreSQL", "MariaDB", "MongoDB", "OCaml", "OpenAL", "OpenDNS", "OpenGL", "OpenMP", "OpenSSH", "OpenSSL", "OpenStreetMap", "OpenTelemetry", "OpenType", "WebGL", "WebGL2", "WebGPU", "WebRTC", "WebSocket", "WebTransport", "WebP", "OpenExr", "YCbCr", "sRGB", "TensorFlow", "TrueType", "iOS", "macOS", "FreeBSD", "NetBSD", "OpenBSD", "NixOS", "TeX", "LaTeX", "BibTeX", "BibLaTeX", "MinGW", "CamelCase"])

From the Clippy lint list (0.1.99), part of the Rust project, MIT or Apache-2.0. Official entry.

Related lints

• too_many_linesChecks for functions with a large amount of lines
• missing_errors_docChecks the doc comments of publicly visible functions that return a Result type and warns if there is no # Errors section
• must_use_candidateChecks for public functions that have no #[must_use] attribute, but return something not already marked must-use, have no mutable arg and mutate no statics
• doc_broken_linkpossible broken doc link: broken across multiple lines
• doc_comment_double_space_linebreaksDetects doc comments that use double spaces as hard line break, instead of backslash (\)
• doc_link_with_quotespossible intra-doc link using quotes instead of backticks
• duration_suboptimal_unitsconstructing a `Duration` using a smaller unit when a larger unit would be more readable
• elidable_lifetime_namesChecks for lifetime annotations which can be replaced with anonymous lifetimes ('_)
• enum_glob_useChecks for use Enum::*

All 847 Clippy lints · Rust compiler errors · Cargo.toml checker