rustdoc: Bad handling of proc_macro's re-exported via use_extern_macros #49553
Labels
A-macros-1.2
Area: Declarative macros 1.2
A-macros-2.0
Area: Declarative macros 2.0 (#39412)
C-enhancement
Category: An issue proposing an enhancement or a PR with one.
T-rustdoc
Relevant to the rustdoc team, which will review and decide on the PR/issue.
Comments
10 tasks
pietroalbini
added
C-enhancement
|
Still broken, looks like. Seems we'll need to properly document proc-macros, and handle their re-export, now. Something that strikes me as odd is that the original crate shows the proc-macro as a function, and it's only when it's re-exported is it seen as a macro:
I think we'll need to handle the |
|
Update: It looks like the odd curly-brace segment of the link is gone, but the links are still broken because rustdoc is still treating proc-macros as functions in their source crate. Not sure what fixed that, but it means one less thing to figure out when fixing this for real. |
|
I've opened #54577 to make rustdoc properly document proc-macros, but there's a wrinkle that means their re-export is still a little awkward (though it's better than before). I wrote more about it in that PR. |
kennytm
added a commit
to kennytm/rust
that referenced
this issue
Sep 29, 2018
…uillaumeGomez rustdoc: give proc-macros their own pages related to rust-lang#49553 but i don't think it'll fix it Currently, rustdoc doesn't expose proc-macros all that well. In the source crate, only their definition function is exposed, but when re-exported, they're treated as a macro! This is an awkward situation in all accounts. This PR checks functions to see whether they have any of `#[proc_macro]`, `#[proc_macro_attribute]`, or `#[proc_macro_derive]`, and exposes them as macros instead. In addition, attributes and derives are exposed differently than other macros, getting their own item-type, CSS class, and module heading.  Function-like proc-macros are lumped in with `macro_rules!` macros, but they get a different declaration block (i'm open to tweaking this, it's just what i thought of given how function-proc-macros operate):  Proc-macro attributes and derives get their own pages, with a representative declaration block. Derive macros also show off their helper attributes:   There's one wrinkle which this PR doesn't address, which is why i didn't mark this as fixing the linked issue. Currently, proc-macros don't expose their attributes or source span across crates, so while rustdoc knows they exist, that's about all the information it gets. This leads to an "inlined" macro that has absolutely no docs on it, and no `[src]` link to show you where it was declared. The way i got around it was to keep proc-macro re-export disabled, since we do get enough information across crates to properly link to the source page:  Until we can get a proc-macro's docs (and ideally also its source span) across crates, i believe this is the best way forward.
asomers
added a commit
to asomers/mockall
that referenced
this issue
Aug 10, 2019
mockall depends on mockall_derive, because it reexports its macros. But mockall_derive has a dev dependency on mockall, because of its doc tests. This makes publishing new versions to crates.io painful, and it recently broke mockall_derive's docs on docs.rs. This commit moves all of mockall_derive's doc tests into mockall by fooling rustdoc. When #[cfg(rustdoc)] is set, mockall doesn't reexport anything from mockall_derive. Instead it defines some empty macros and documents those instead. It's not perfect, but it'll have to do until there's a better solution for rust-lang/rust#49553 . CC @jasongrlicky
asomers
added a commit
to asomers/mockall
that referenced
this issue
Aug 10, 2019
mockall depends on mockall_derive, because it reexports its macros. But mockall_derive has a dev dependency on mockall, because of its doc tests. This makes publishing new versions to crates.io painful, and it recently broke mockall_derive's docs on docs.rs. This commit moves all of mockall_derive's doc tests into mockall by fooling rustdoc. When #[cfg(rustdoc)] is set, mockall doesn't reexport anything from mockall_derive. Instead it defines some empty macros and documents those instead. It's not perfect, but it'll have to do until there's a better solution for rust-lang/rust#49553 . CC @jasongrlicky
Centril
added a commit
to Centril/rust
that referenced
this issue
Aug 24, 2019
…final, r=petrochenkov Improve Rustdoc's handling of procedural macros Fixes rust-lang#58700 Fixes rust-lang#58696 Fixes rust-lang#49553 Fixes rust-lang#52210 This commit removes the special rustdoc handling for proc macros, as we can now retrieve their span and attributes just like any other item. A new command-line option is added to rustdoc: `--crate-type`. This takes the same options as rustc's `--crate-type` option. However, all values other than `proc-macro` are treated the same. This allows Rustdoc to enable 'proc macro mode' when handling a proc macro crate. In compiletest, a new 'rustdoc-flags' option is added. This allows us to pass in the '--proc-macro-crate' flag in the absence of Cargo. I've opened [an additional PR to Cargo](rust-lang/cargo#7159) to support passing in this flag. These two PRS can be merged in any order - the Cargo changes will not take effect until the 'cargo' submodule is updated in this repository.
Centril
added a commit
to Centril/rust
that referenced
this issue
Aug 24, 2019
…final, r=petrochenkov Improve Rustdoc's handling of procedural macros Fixes rust-lang#58700 Fixes rust-lang#58696 Fixes rust-lang#49553 Fixes rust-lang#52210 This commit removes the special rustdoc handling for proc macros, as we can now retrieve their span and attributes just like any other item. A new command-line option is added to rustdoc: `--crate-type`. This takes the same options as rustc's `--crate-type` option. However, all values other than `proc-macro` are treated the same. This allows Rustdoc to enable 'proc macro mode' when handling a proc macro crate. In compiletest, a new 'rustdoc-flags' option is added. This allows us to pass in the '--proc-macro-crate' flag in the absence of Cargo. I've opened [an additional PR to Cargo](rust-lang/cargo#7159) to support passing in this flag. These two PRS can be merged in any order - the Cargo changes will not take effect until the 'cargo' submodule is updated in this repository.
bors
added a commit
that referenced
this issue
Aug 29, 2019
…trochenkov Improve Rustdoc's handling of procedural macros Fixes #58700 Fixes #58696 Fixes #49553 Fixes #52210 This commit removes the special rustdoc handling for proc macros, as we can now retrieve their span and attributes just like any other item. A new command-line option is added to rustdoc: `--crate-type`. This takes the same options as rustc's `--crate-type` option. However, all values other than `proc-macro` are treated the same. This allows Rustdoc to enable 'proc macro mode' when handling a proc macro crate. In compiletest, a new 'rustdoc-flags' option is added. This allows us to pass in the '--proc-macro-crate' flag in the absence of Cargo. I've opened [an additional PR to Cargo](rust-lang/cargo#7159) to support passing in this flag. These two PRS can be merged in any order - the Cargo changes will not take effect until the 'cargo' submodule is updated in this repository.
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
If you define a proc-macro in one crate, then re-export it from another crate via the
use_extern_macrosfeature the resulting documentation does not link to the macro correctly, and the tooltip has some weird details displayed in it:link:
../proc_macro_re_export_proc_macro/macro.%7B%7BGlobalMetaData::Krate%7D%7D.htmlThe text was updated successfully, but these errors were encountered: