Uh oh!
There was an error while loading. Please reload this page.
Improve Rustdoc's handling of procedural macros - #62855
Merged
Merged
Conversation
petrochenkov
commented
Jul 22, 2019
Contributor
@Aaron1011 |
bors
commented
Jul 27, 2019
Collaborator
☔ The latest upstream changes (presumably #62086) made this pull request unmergeable. Please resolve the merge conflicts. |
Aaron1011force-pushed
the
feature/rustdoc-reexport-final
branch
from
July 27, 2019 16:56
fd5d16d to
892b81fComparerust-highfive
commented
Jul 27, 2019
Contributor
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.
Aaron1011
commented
Jul 27, 2019
ContributorAuthor
@petrochenkov: I've split the |
Aaron1011
commented
Jul 27, 2019
ContributorAuthor
Note that due to changes in the metadata format, you should run |
bors
commented
Jul 28, 2019
Collaborator
☔ The latest upstream changes (presumably #63057) made this pull request unmergeable. Please resolve the merge conflicts. |
Aaron1011force-pushed
the
feature/rustdoc-reexport-final
branch
from
July 28, 2019 15:29
e2efa77 to
cbea48cCompareContributor
(@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.) |
petrochenkov
commented
Aug 2, 2019
Contributor
cc @eddyb, especially regarding the metadata bits. |
bors
commented
Aug 3, 2019
Collaborator
☔ The latest upstream changes (presumably #63234) made this pull request unmergeable. Please resolve the merge conflicts. |
Aaron1011force-pushed
the
feature/rustdoc-reexport-final
branch
from
August 4, 2019 02:13
cbea48c to
ef755fcComparebors 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.
petrochenkov
commented
Aug 4, 2019
Contributor
Ok, let's do the next thing.
This is an important problem to solve and I'm glad someone is working on it, thanks. |
Uh oh!
There was an error while loading. Please reload this page.
Aaron1011force-pushed
the
feature/rustdoc-reexport-final
branch
from
August 4, 2019 21:09
ef755fc to
e38ddc4CompareAaron1011
commented
Aug 24, 2019
ContributorAuthor
Also, this PR should be |
Centril
commented
Aug 25, 2019
Contributor
Failed in #63864 (comment), @bors r- |
Centril
commented
Aug 25, 2019
Contributor
@bors retry |
…e-type proc-macro' Add a test to make sure that this works
Aaron1011
commented
Aug 28, 2019
ContributorAuthor
@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. |
Aaron1011
commented
Aug 28, 2019
ContributorAuthor
@rustbot modify labels to +S-waiting-on-review, -S-waiting-on-bors |
petrochenkov
commented
Aug 28, 2019
Contributor
@bors r+ |
bors
commented
Aug 28, 2019
Collaborator
📌 Commit 4c3e386 has been approved by |
bors
commented
Aug 29, 2019
Collaborator
bors added a commit
that referenced
this pull request
Aug 29, 2019
…trochenkov Improve Rustdoc's handling of procedural macros Fixes#58700Fixes#58696Fixes#49553Fixes#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
commented
Aug 29, 2019
Collaborator
☀️ Test successful - checks-azure |
rust-highfive
commented
Aug 29, 2019
Contributor
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).
This file contains hidden or 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
Sign up for freeto join this conversation on GitHub.
Already have an account?
Sign in to comment
9 participants
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.