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

Deriving proc_macros should be documented under their exported name #52210

Closed
alercah opened this issue Jul 10, 2018 · 1 comment · Fixed by #62855
Closed

Deriving proc_macros should be documented under their exported name #52210

alercah opened this issue Jul 10, 2018 · 1 comment · Fixed by #62855
Labels
T-rustdoc Relevant to the rustdoc team, which will review and decide on the PR/issue.

Comments

@alercah
Copy link
Contributor

alercah commented Jul 10, 2018

The serde_derive crate exports derivation macros for Deserialize and Serialize. The actual functions implementing these macros are named derive_deserialize and derive_serialize, and that is what they are listed under in Rustdoc. This is not the actual exported name, however; they are exported under the names Deserialize and Serialize, as specified in the proc_macro_derive attribute.

This hasn't mattered as much in the past, but in Rust 2018, the new macro import feature requires you to be able to name the macro as exported:

use serde_derive::Deserialize; // not use serde_derive::derive_deserialize;

While proc_macro_derive's behaviour here is a bit weird and the attribute has a number of other issues, those need to be addressed comprehensively and definitely won't be in time for 2018.
@alercah
Copy link
Contributor Author

alercah commented Jul 10, 2018

Addendum: this should probably also include auxiliary attributes specified by the attribute parameter on proc_macro_derive.

@steveklabnik steveklabnik added the T-rustdoc Relevant to the rustdoc team, which will review and decide on the PR/issue. label Jul 10, 2018
@Aaron1011 Aaron1011 mentioned this issue Jul 21, 2019
Merged
Centril added a commit to Centril/rust that referenced this issue Aug 24, 2019
@Centril
Rollup merge of rust-lang#62855 - Aaron1011:feature/rustdoc-reexport-…
3733450 
…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
@Centril
Rollup merge of rust-lang#62855 - Aaron1011:feature/rustdoc-reexport-…
1a89e16 
…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
@bors
Auto merge of #62855 - Aaron1011:feature/rustdoc-reexport-final, r=pe…
3476543 
…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.
@bors bors closed this as completed in 1498608 Aug 29, 2019
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Assignees
No one assigned
Labels
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.

Improve Rustdoc's handling of procedural macros Aaron1011/rust
2 participants
@steveklabnik @alercah