rust-lang / rust-lang/rust

rustdoc leaks `ident` macro meta-variables in non-literal const exprs in assoc tys & impl trait refs (excl. self ty)

Open
#127,429 0 comments 0 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

A-const-generics A-macros C-bug T-rustdoc
Dominant language
Rust
Stars
119k
Forks
16.1k
PR merge metrics
PR metrics pending

Description

Minimal reproduction:

pub struct S<const A: bool>;

pub const TRUE: bool = true;

macro_rules! example {
    ($unexpanded:ident) => {
        impl core::ops::Add<S<$unexpanded>> for S<$unexpanded> {
            type Output = S<$unexpanded>;

            fn add(self, _: S<$unexpanded>) -> Self::Output {
                S::<$unexpanded>
            }
        }
    };
}

example!(TRUE);

When I generate documentation for this with cargo doc, the documentation for S's trait implementations says

impl Add<S<$unexpanded>> for S<TRUE>
type Output = S<$unexpanded>

I expected the documentation to document the expanded code. It happens with both 1.79 and nightly.

The problem persists if I change the macro to put {} around $unexpanded, but then if I pass true instead of TRUE to the macro, it's expanded and shown as impl Add for S<{ true }> and type Output = S<true> (without the {})

% rustc --version --verbose
rustc 1.79.0 (129f3b996 2024-06-10)
binary: rustc
commit-hash: 129f3b9964af4d4a709d1383930ade12dfe7c081
commit-date: 2024-06-10
host: aarch64-apple-darwin
release: 1.79.0
LLVM version: 18.1.7

% rustc +nightly --version --verbose
rustc 1.81.0-nightly (8337ba918 2024-06-12)
binary: rustc
commit-hash: 8337ba9189de188e2ed417018af2bf17a57d51ac
commit-date: 2024-06-12
host: aarch64-apple-darwin
release: 1.81.0-nightly
LLVM version: 18.1.7

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

Start by reproducing the minimal macro example with cargo doc on the reported stable and nightly versions, then inspect the generated documentation for the Add implementation and associated Output type. Trace how rustdoc handles macro meta-variables in non-literal const expressions and impl trait references. Done means the generated documentation shows the expanded code rather than $unexpanded.

Written by the indexing model from the issue text.

Assessment

Tech stack
rust
Domain
compilers, documentation
Issue type
Bug
Difficulty
4/5
Estimated time
3-5 days
Activity status
Stale
Clarity
Mostly clear
Newbie friendliness
35/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.