rust-lang / rust-lang/rust-clippy

New lint: `doc_hidden_item_used`

Open
#11,536 5 comments 1 reaction 0 assignees View on GitHub

Nobody has claimed this yet.

A-lint
Dominant language
Rust
Stars
13.5k
Forks
2.2k
Avg merge
2d 10h
Merged PRs (30d)
32

Description

What it does

This lint triggers when a item declared with #[doc(hidden)] is used outside of the crate where the item is declared and outside of a macro expansion.

Advantage

Most #[doc(hidden)] items are not meant to be part of the public API and are only there to allow macros to access "internals" of the crate.
As such, using such an item is generally a bad idea.

Drawbacks

There can be cases where such an item is still part of the public API but hidden. The only case I know of that is serde's deserialize_in_place.

I also know that TypedBuilder uses #[doc(hidden)] on the builder type, but I believe the lint should not trigger in that case. The builder is obtained with the documented pub fn builder() method, and the methods of the builder themselves are not #[doc(hidden)]. Since the builder type is never explicitly referenced when used, this lint should not trigger.

Example

In crate crate_a:

#[doc(hidden)]
struct A;

In crate B:

fn main() {
    // This triggers the lint.
    let a = crate_a::A;
}

Contributor guide

Open the contributing guide

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

Research direction

No repository files, tests, or entry points are named in the issue. Start by locating Clippy's existing lint implementations and UI-test conventions, then use the provided crate_a and crate B example to verify the intended diagnostic and the macro-expansion exception. Done means the lint handles the described cross-crate use without flagging macro expansions.

Written by the indexing model from the issue text.

Assessment

Tech stack
rust
Domain
tooling
Issue type
Feature
Difficulty
4/5
Estimated time
3-5 days
Activity status
Stale
Clarity
Mostly clear
Newbie friendliness
42/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.