Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

Incorrect mixing of reexport and definition documentation of proc macros #64251

Closed
LukasKalbertodt opened this issue Sep 7, 2019 · 4 comments · Fixed by #64528
Closed

Incorrect mixing of reexport and definition documentation of proc macros #64251

LukasKalbertodt opened this issue Sep 7, 2019 · 4 comments · Fixed by #64528
Labels
A-macros Area: All kinds of macros (custom derive, macro_rules!, proc macros, ..) C-bug Category: This is a bug. T-rustdoc Relevant to the rustdoc team, which will review and decide on the PR/issue.

Comments

@LukasKalbertodt
Copy link
Member

The PR #62855 improved the situation about documenting proc macros. Thanks for that! However, I noticed a bug with it. I'm using rustc 1.39.0-nightly (6e19f3f38 2019-09-06).

Cargo.toml

[package]
name = "doc-bug"
version = "0.1.0"
authors = ["me"]
edition = "2018"

[dependencies]
macros = { path = "macros" }

src/lib.rs

/// Reexport `foo`.
pub use macros::foo;

/// Reexport `Bar`.
pub use macros::Bar;

/// Reexport `Baz`.
pub use macros::Baz;

macros/Cargo.toml

[package]
name = "macros"
version = "0.1.0"
authors = ["me"]
edition = "2018"

[lib]
proc-macro = true

macros/src/lib.rs

extern crate proc_macro;

use proc_macro::TokenStream;

/// Definition `foo`.
#[proc_macro]
pub fn foo(input: TokenStream) -> TokenStream {
    input
}

/// Definition `Bar`.
#[proc_macro_derive(Bar)]
pub fn bar(input: TokenStream) -> TokenStream {
    input
}

/// Definition `Baz`.
#[proc_macro_derive(Baz)]
pub fn baz(input: TokenStream) -> TokenStream {
    input
}

Running cargo doc results in this:

image

Looks like a simple typo or off-by-one or something like that bug. When using only proc_macro and not proc_macro_derives, everything looks good to me.

CC @Aaron1011
@LukasKalbertodt
Copy link
Member Author

Oh, and also, running cargo doc prints:

   Compiling macros v0.1.0 (/home/lukas/dev/doc-bug/macros)
 Documenting macros v0.1.0 (/home/lukas/dev/doc-bug/macros)
warning: Trying to document proc macro crate without passing '--crate-type proc-macro to rustdoc
  |
  = warning: The generated documentation may be incorrect

 Documenting doc-bug v0.1.0 (/home/lukas/dev/doc-bug)
    Finished dev [unoptimized + debuginfo] target(s) in 1.71s

Not sure if this warning is expected there. And not sure if related to this bug.

@Centril Centril added C-bug Category: This is a bug. T-rustdoc Relevant to the rustdoc team, which will review and decide on the PR/issue. A-macros Area: All kinds of macros (custom derive, macro_rules!, proc macros, ..) labels Sep 7, 2019
@Aaron1011
Copy link
Member

This is a consequence of the fact that rust-lang/cargo#7159 has not yet been merged. Once it gets merged, and rust updates its Cargo submodule, this issue should go away.

@Aaron1011 Aaron1011 mentioned this issue Sep 16, 2019
Merged
@Aaron1011
Copy link
Member

@LukasKalbertodt: It turns out that this issue was unrelated. I've opened a PR to fix it.

@LukasKalbertodt
Copy link
Member Author

@Aaron1011 I see. Thanks for your work on this :)

tmandry added a commit to tmandry/rust that referenced this issue Sep 18, 2019
@tmandry
Rollup merge of rust-lang#64528 - Aaron1011:fix/proc-macro-type, r=al…
fbd1144 
…excrichton

Load proc macro metadata in the correct order.

Serialized proc macro metadata is assumed to have a one-to-one
correspondence with the entries in static array generated by proc_macro_harness.
However, we were previously serializing proc macro metadata in a
different order than proc macros were laied out in the static array.
This lead to us associating the wrong data with a proc macro when
generating documentation, causing Rustdoc to generate incorrect docs for
proc macros.

This commit keeps track of the order in which we insert proc macros into
the generated static array. We use this same order when serializing proc
macro metadata, ensuring that we can later associate the metadata for a
proc macro with its entry in the static array.

Fixes rust-lang#64251
tmandry added a commit to tmandry/rust that referenced this issue Sep 18, 2019
@tmandry
Rollup merge of rust-lang#64528 - Aaron1011:fix/proc-macro-type, r=al…
987e712 
…excrichton

Load proc macro metadata in the correct order.

Serialized proc macro metadata is assumed to have a one-to-one
correspondence with the entries in static array generated by proc_macro_harness.
However, we were previously serializing proc macro metadata in a
different order than proc macros were laied out in the static array.
This lead to us associating the wrong data with a proc macro when
generating documentation, causing Rustdoc to generate incorrect docs for
proc macros.

This commit keeps track of the order in which we insert proc macros into
the generated static array. We use this same order when serializing proc
macro metadata, ensuring that we can later associate the metadata for a
proc macro with its entry in the static array.

Fixes rust-lang#64251
tmandry added a commit to tmandry/rust that referenced this issue Sep 18, 2019
@tmandry
Rollup merge of rust-lang#64528 - Aaron1011:fix/proc-macro-type, r=al…
76d34f3 
…excrichton

Load proc macro metadata in the correct order.

Serialized proc macro metadata is assumed to have a one-to-one
correspondence with the entries in static array generated by proc_macro_harness.
However, we were previously serializing proc macro metadata in a
different order than proc macros were laied out in the static array.
This lead to us associating the wrong data with a proc macro when
generating documentation, causing Rustdoc to generate incorrect docs for
proc macros.

This commit keeps track of the order in which we insert proc macros into
the generated static array. We use this same order when serializing proc
macro metadata, ensuring that we can later associate the metadata for a
proc macro with its entry in the static array.

Fixes rust-lang#64251
@bors bors closed this as completed in 3daa8bd Sep 18, 2019
@Aaron1011 Aaron1011 mentioned this issue Feb 3, 2020
Closed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Assignees
No one assigned
Labels
A-macros Area: All kinds of macros (custom derive, macro_rules!, proc macros, ..) C-bug Category: This is a bug. T-rustdoc Relevant to the rustdoc team, which will review and decide on the PR/issue.
Projects
None yet
Milestone
No milestone
Development

Successfully merging a pull request may close this issue.

Load proc macro metadata in the correct order. Aaron1011/rust
3 participants
@Centril @Aaron1011 @LukasKalbertodt