Improve Rustdoc's handling of procedural macros #62855
Merged
Conversation
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
petrochenkov
added
the
S-waiting-on-review
|
@Aaron1011 |
petrochenkov
added
S-waiting-on-author
|
☔ The latest upstream changes (presumably #62086) made this pull request unmergeable. Please resolve the merge conflicts. |
Aaron1011
force-pushed
the
feature/rustdoc-reexport-final
branch
from
fd5d16d
to
892b81f
Compare
|
The job Click to expand the log.I'm a bot! I can only do what humans tell me to, so if this was not helpful or you have suggestions for improvements, please ping or otherwise contact |
Aaron1011
added a commit
to Aaron1011/rust
that referenced
this pull request
Jul 27, 2019
Split off from rust-lang#62855 Currently, rustdoc ignores any doc comments found on 'pub use' statements. As described in issue rust-lang#58700, this makes it impossible to properly document procedural macros. Any doc comments must be written on the procedural macro definition, which must occur in a dedicated proc-macro crate. This means that any doc comments or doc tests cannot reference items defined in re-exporting crate, despite the fact that such items may be required to use the procedural macro. To solve this issue, this commit allows doc comments to be written on 'pub use' statements. For consistency, this applies to *all* 'pub use' statements, not just those importing procedural macros. When inlining documentation, documentation on 'pub use' statements will be prepended to the documentation of the inlined item. For example, the following items: ```rust mod other_mod { /// Doc comment from definition pub struct MyStruct; } /// Doc comment from 'pub use' /// pub use other_mod::MyStruct; ``` will caues the documentation for the re-export of 'MyStruct' to be rendered as: ``` Doc comment from 'pub use' Doc comment from definition ``` Note the empty line in the 'pub use' doc comments - because doc comments are concatenated as-is, this ensure that the doc comments on the definition start on a new line.
|
@petrochenkov: I've split the |
|
Note that due to changes in the metadata format, you should run |
|
☔ The latest upstream changes (presumably #63057) made this pull request unmergeable. Please resolve the merge conflicts. |
petrochenkov
added
S-waiting-on-review
Aaron1011
force-pushed
the
feature/rustdoc-reexport-final
branch
from
e2efa77
to
cbea48c
Compare
|
(@Aaron1011, if you have time, could you squash the commits to entirely remove traces of #63048 from this PR. I have a few busy days, but hope to return to this PR this week.) |
|
cc @eddyb, especially regarding the metadata bits. |
|
☔ The latest upstream changes (presumably #63234) made this pull request unmergeable. Please resolve the merge conflicts. |
Aaron1011
force-pushed
the
feature/rustdoc-reexport-final
branch
from
cbea48c
to
ef755fc
Compare
bors
added a commit
that referenced
this pull request
Aug 4, 2019
…laumeGomez Use doc comments from 'pub use' statements Split off from #62855 Currently, rustdoc ignores any doc comments found on 'pub use' statements. As described in issue #58700, this makes it impossible to properly document procedural macros. Any doc comments must be written on the procedural macro definition, which must occur in a dedicated proc-macro crate. This means that any doc comments or doc tests cannot reference items defined in re-exporting crate, despite the fact that such items may be required to use the procedural macro. To solve this issue, this commit allows doc comments to be written on 'pub use' statements. For consistency, this applies to *all* 'pub use' statements, not just those importing procedural macros. When inlining documentation, documentation on 'pub use' statements will be prepended to the documentation of the inlined item. For example, the following items: ```rust mod other_mod { /// Doc comment from definition pub struct MyStruct; } /// Doc comment from 'pub use' /// pub use other_mod::MyStruct; ``` will caues the documentation for the re-export of 'MyStruct' to be rendered as: ``` Doc comment from 'pub use' Doc comment from definition ``` Note the empty line in the 'pub use' doc comments - because doc comments are concatenated as-is, this ensure that the doc comments on the definition start on a new line.
|
Ok, let's do the next thing.
This is an important problem to solve and I'm glad someone is working on it, thanks. |
petrochenkov
reviewed
Aug 4, 2019
petrochenkov
added
S-waiting-on-author
Aaron1011
force-pushed
the
feature/rustdoc-reexport-final
branch
from
ef755fc
to
e38ddc4
Compare
|
Also, this PR should be |
|
Failed in #63864 (comment), @bors r- |
bors
added
S-waiting-on-author
|
@bors retry |
bors
added
S-waiting-on-bors
…e-type proc-macro' Add a test to make sure that this works
|
@petrochenkov: As discussed in rust-lang/cargo#7159, I've modified this PR to support documenting proc-macro crates when This PR should now be ready to merge. |
|
@rustbot modify labels to +S-waiting-on-review, -S-waiting-on-bors |
rustbot
added
S-waiting-on-review
|
@bors r+ |
|
📌 Commit 4c3e386 has been approved by |
bors
added
S-waiting-on-bors
bors
added a commit
that referenced
this pull request
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.
|
☀️ Test successful - checks-azure |
rust-highfive
added a commit
to rust-lang-nursery/rust-toolstate
that referenced
this pull request
Aug 29, 2019
Tested on commit rust-lang/rust@3476543. Direct link to PR: <rust-lang/rust#62855> 💔 rustc-guide on linux: test-pass → test-fail (cc @mark-i-m @spastorino @amanjeev, @rust-lang/infra).
bors
added a commit
to rust-lang/cargo
that referenced
this pull request
Sep 16, 2019
…lexcrichton Pass --crate-type to rustdoc This supports the [corresponding rustc PR](rust-lang/rust#62855). To enable rustdoc to properly document macros, we pass a new flag '--proc-macro-crate' when documenting a proc-macro crate. This causes rustdoc to enable the proc-macro compiler logic that runs when rustc is building a proc-macro crate. This flag is essentially a more restricted version of '--crate-type=proc-macro'. I didn't think it was necessary to pass the full '--crate-type' flag to rustdoc, when only two options would ever be used (proc-macro vs anything else).
compiler-errors
added a commit
to compiler-errors/rust
that referenced
this pull request
Feb 25, 2023
…=estebank [breaking change] Remove a rustdoc back compat warning This warning was introduced in rust-lang#62855 for users who use `rustdoc` directly on proc macro crates (instead of using `cargo doc`) without passing `--crate-type proc-macro` (which `cargo doc` passed automatically).
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
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-typeoption. However, all values other thanproc-macroare 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 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.