rust-lang / rust-lang/docs.rs

`rustdoc-args` is ignored for proc_macro crates

Open
#2,374 4 comments 0 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

A-builds C-bug
Dominant language
Rust
Stars
1.2k
Forks
232
Avg merge
11h 35m
Merged PRs (30d)
60

Description

Crate name

attr_alias

Build failure link

https://docs.rs/crate/attr_alias/0.1.0/builds/1075851

Additional details

The build did not fail, but this still appeared to be the best template, as the build did not work as expected.

For proc_macro crates, docs.rs avoids passing --target for builds:
https://github.com/rust-lang/docs.rs/blob/b0f6feadba64502c8aa68dedc3e20be096c5af23/src/docbuilder/rustwide_builder.rs#L830-L833

From what I can tell, for library crates, this fixes an issue of rustdoc-args being ignored when passed as build.rustdocflags to rustdoc. However, regardless of whether --target is passed, rustdoc-args is ignored for proc_macro crates.

For example, Cargo.toml for attr_alias includes:

[package.metadata.docs.rs]
rustdoc-args = ["--cfg", "attr_alias_docs_rs"]

attr_alias::attr_alias also has the attribute:

#[cfg_attr(attr_alias_docs_rs, doc(cfg(feature = "nightly")))]

Therefore, attr_alias::attr_alias should be documented to require the "nightly" feature, but the note is missing, since rustdoc-args was ignored:
https://docs.rs/attr_alias/0.1.0/attr_alias/attr.attr_alias.html

Contributor guide

No contributing guide indexed for this repository

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 in src/docbuilder/rustwide_builder.rs around lines 830-833 and trace the proc_macro build path where --target is omitted. Reproduce the attr_alias 0.1.0 case using its docs.rs configuration, then verify that rustdoc-args reaches rustdoc and the generated documentation shows the nightly feature requirement.

Written by the indexing model from the issue text.

Assessment

Tech stack
rust
Domain
build-system, documentation
Issue type
Bug
Difficulty
4/5
Estimated time
3-5 days
Activity status
Stale
Clarity
Clearly specified
Newbie friendliness
45/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.