Can't document rustc-macro crates

[alexcrichton]

Originally filed as rust-lang/cargo#3132 by @dtolnay

Reported by @neon64 in serde-rs/serde#567: cargo doc cannot document any rustc_macro crate or any crate depending on a rustc_macro crate.

https://docs.rs/crate/serde_derive/0.8.10/builds/31363

error: the `#[rustc_macro_derive]` attribute is only usable with crates of the `rustc-macro` crate type
 --> .cargo/registry/src/github.aaakk.us.kg-1ecc6299db9ec823/serde_derive-0.8.10/src/lib.rs:9:3
  |
9 | #[rustc_macro_derive(Serialize)]
  |   ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

error: the `#[rustc_macro_derive]` attribute is only usable with crates of the `rustc-macro` crate type
  --> .cargo/registry/src/github.aaakk.us.kg-1ecc6299db9ec823/serde_derive-0.8.10/src/lib.rs:18:3
   |
18 | #[rustc_macro_derive(Deserialize)]
   |   ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

error: Compilation failed, aborting rustdoc

@alexcrichton I don't know Cargo well enough to tell whether this is a cargo issue or a rustc issue or a rustdoc issue so sorry if this is filed in the wrong place.

[alexcrichton]

@nrc curious about your thoughts on how we might fix this.

The problem here is that rustdoc doesn't have a --crate-type argument, so Cargo doesn't pass it. Instead rustdoc hard codes that all crates are rlibs when we document them. This then doesn't play nicely with the attribute which requires a rustc macro crate type. I see two solutions currently:

• Cargo never documents rustc-macro crates
• The compiler ignores requirements of the rustc-macro crate type if we're in "rustdoc mode"

The former seems reasonable for now but eventually rustc-macro crates will grow to perhaps having interesting APIs in them, right? The latter unfortunately doesn't have a great way to do so today but I could always add a random flag to the session.

[nrc]

Depending on how long "eventually" is we might be best waiting to separate Rustdoc out from the compiler. It might still need something hacked in to the session though (depending on how it is implemented). Given that it is Rustdoc, I'd not be opposed to the hackiest of hacks to get this working.

[dtolnay]

Agreed on a quick hack to get this working if a real fix is further out - not being able to document any crate that transitively depends on serde_derive is a pretty big blocker. I don't think anybody cares whether serde_derive itself is rustdocumented at this point.

[steveklabnik]

I would really like to separate rustdoc from the compiler. It's on my
"someday" list.

On Thu, Sep 29, 2016 at 5:03 PM, David Tolnay [email protected]
wrote:

Agreed on a quick hack to get this working if a real fix is further out -
not being able to document any crate that transitively depends on
serde_derive is a pretty big blocker. I don't think anybody cares whether
serde_derive itself is rustdocumented at this point.

—
You are receiving this because you are subscribed to this thread.
Reply to this email directly, view it on GitHub
#36820 (comment),
or mute the thread
https://github.com/notifications/unsubscribe-auth/AABsinG-Agl5wlBOsMMl9skNjS9lWeniks5qvCe3gaJpZM4KJjtY
.