Deprecate doc(include)
#82539
Closed
Deprecate doc(include)
#82539
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
jyn514
added
T-rustdoc
rust-highfive
added
the
S-waiting-on-review
This comment has been minimized.
This comment has been minimized.
jyn514
force-pushed
the
deprecate-doc-include
branch
from
0ec9b2e
to
6528ef3
Compare
3 tasks
|
Should this be |
rust-lang/rfcs#1990 (comment):
|
|
@rfcbot fcp merge |
|
Team member @jyn514 has proposed to merge this. The next step is review by the rest of the tagged team members: Concerns:
Once a majority of reviewers approve (and at most 2 approvals are outstanding), this will enter its final comment period. If you spot a major issue that hasn't been raised at any point in this process, please speak up! See this document for info about what commands tagged team members can give me. |
rfcbot
added
proposed-final-comment-period
GuillaumeGomez
approved these changes
Feb 26, 2021
rfcbot
added
final-comment-period
|
🔔 This is now entering its final comment period, as per the review above. 🔔 |
camelid
reviewed
Feb 26, 2021
This comment has been minimized.
This comment has been minimized.
This comment has been minimized.
This comment has been minimized.
jyn514
force-pushed
the
deprecate-doc-include
branch
from
380259b
to
4e4223d
Compare
|
I've found that: #![cfg_attr(
feature = "nightly",
feature(external_doc),
doc(include = "../README.md")
)]can be compiled if the crate feature But this can't: #![cfg_attr(
feature = "nightly",
feature(extended_key_value_attributes),
doc = include_str!("../README.md")
)]I would prefer if |
|
Personally, I would rather that be fixed by stabilizing |
This comment has been minimized.
This comment has been minimized.
|
@rfcbot concern doctest-span How will this interact with #81070? Specifically, will it be feasible to use the source span in the included file for |
rfcbot
added
proposed-final-comment-period
|
Oops, didn't realize that would cancel the FCP... |
## Why deprecate doc(include)?
This nightly feature is a strictly less general version of
`extended_key_value_attributes`, which looks like this:
```
#[doc = include_str!("docs.md")]
```
In particular, that feature allows manipulating the filename and
included docs in a way that `doc(include)` cannot, due to eager
evaluation:
```
#[doc = concat!(
"These are my docs: ",
include_str!(concat!(env!("OUT_DIR"), "generated_docs.md"))
)]
```
For more about eager evaluation and how it impacts macro parsing,
see petrochenkov's excellent writeup: https://internals.rust-lang.org/t/macro-expansion-points-in-attributes/11455
Given that `#[doc(include)]` offers no features that
`extended_key_value_attributes` cannot, it makes no sense for the
language and rustdoc to maintain it indefinitely. This deprecates
`doc(include)` and adds a structured suggestion to switch to switch to
`doc = include_str!` instead.
## Implementation
Notably, this changes attribute cleaning to pass in whether an item is
local or not. This is necessary to avoid warning about `doc(include)` in
dependencies (see rust-lang#82284 for the
sort of trouble that can cause).
This allows calling `tcx.struct_span_lint_hir` in the next commit. It also slightly shortens the code.
jyn514
force-pushed
the
deprecate-doc-include
branch
from
1247250
to
98fcb6c
Compare
|
The job Click to see the possible cause of the failure (guessed by this bot) |
camelid
reviewed
Apr 9, 2021
| /// | ||
| /// This is a `rustdoc` only lint, see the documentation in the [rustdoc book]. | ||
| /// | ||
| /// [rustdoc book]: ../../../rustdoc/lints.html#non_autolinks |
There was a problem hiding this comment.
This link is incorrect:
Suggested change
| /// [rustdoc book]: ../../../rustdoc/lints.html#non_autolinks | |
| /// [rustdoc book]: ../../../rustdoc/lints.html#doc_include |
| reference: "issue #44732 <https://github.com/rust-lang/rust/issues/44732>", | ||
| edition: None, | ||
| }; | ||
| } |
There was a problem hiding this comment.
Maybe a compromise would be to add a more general rustdoc::deprecated_features lint or something like that instead? Then we could use it for other features as well.
bors
added a commit
to rust-lang-ci/rust
that referenced
this pull request
Apr 12, 2021
Update stdarch submodule (to before it switched to const generics) rust-lang#83278 (comment): This unblocks rust-lang#82539. Major changes: - More AVX-512 intrinsics. - More ARM & AArch64 NEON intrinsics. - Updated unstable WASM intrinsics to latest draft standards. - std_detect is now a separate crate instead of a submodule of std. I double-checked and the first use of const generics looks like rust-lang/stdarch@8d50178, which isn't included in this PR. r? `@Amanieu`
jyn514
removed
the
S-blocked
|
I don't have the energy to argue about this. @petrochenkov it's a little frustrating to me that you keep bringing up these issues multiple weeks after the FCP is accepted and the comment period ends. You've done this before too: #77489 (comment) |
jhernandez-at-wiris
pushed a commit
to jhg/opaque-pointer-rs
that referenced
this pull request
Apr 18, 2021
jhernandez-at-wiris
pushed a commit
to jhg/opaque-pointer-rs
that referenced
this pull request
Apr 18, 2021
jhernandez-at-wiris
pushed a commit
to jhg/opaque-pointer-rs
that referenced
this pull request
Apr 18, 2021
jhernandez-at-wiris
pushed a commit
to jhg/opaque-pointer-rs
that referenced
this pull request
Apr 18, 2021
jhernandez-at-wiris
pushed a commit
to jhg/opaque-pointer-rs
that referenced
this pull request
Apr 18, 2021
Dylan-DPC-zz
pushed a commit
to Dylan-DPC-zz/rust
that referenced
this pull request
May 18, 2021
…=petrochenkov Stabilize extended_key_value_attributes Closes rust-lang#44732. Closes rust-lang#78835. Closes rust-lang#82768 (by making it irrelevant). # Stabilization report ## Summary This stabilizes using macro expansion in key-value attributes, like so: ```rust #[doc = include_str!("my_doc.md")] struct S; #[path = concat!(env!("OUT_DIR"), "/generated.rs")] mod m; ``` See Petrochenkov's excellent blog post [on internals](https://internals.rust-lang.org/t/macro-expansion-points-in-attributes/11455) for alternatives that were considered and rejected ("why accept no more and no less?") This has been available on nightly since 1.50 with no major issues. ## Notes ### Accepted syntax The parser accepts arbitrary Rust expressions in this position, but any expression other than a macro invocation will ultimately lead to an error because it is not expected by the built-in expression forms (e.g., `#[doc]`). Note that decorators and the like may be able to observe other expression forms. ### Expansion ordering Expansion of macro expressions in "inert" attributes occurs after decorators have executed, analogously to macro expressions appearing in the function body or other parts of decorator input. There is currently no way for decorators to accept macros in key-value position if macro expansion must be performed before the decorator executes (if the macro can simply be copied into the output for later expansion, that can work). ## Test cases - https://github.com/rust-lang/rust/blob/master/src/test/ui/attributes/key-value-expansion-on-mac.rs - https://github.com/rust-lang/rust/blob/master/src/test/rustdoc/external-doc.rs The feature has also been dogfooded extensively in the compiler and standard library: - rust-lang#83329 - rust-lang#83230 - rust-lang#82641 - rust-lang#80534 ## Implementation history - Initial proposal: rust-lang#55414 (comment) - Experiment to see how much code it would break: rust-lang#67121 - Preliminary work to restrict expansion that would conflict with this feature: rust-lang#77271 - Initial implementation: rust-lang#78837 - Fix for an ICE: rust-lang#80563 ## Unresolved Questions ~~rust-lang#83366 (comment) listed some concerns, but they have been resolved as of this final report.~~ ## Additional Information There are two workarounds that have a similar effect for `#[doc]` attributes on nightly. One is to emulate this behavior by using a limited version of this feature that was stabilized for historical reasons: ```rust macro_rules! forward_inner_docs { ($e:expr => $i:item) => { #[doc = $e] $i }; } forward_inner_docs!(include_str!("lib.rs") => struct S {}); ``` This also works for other attributes (like `#[path = concat!(...)]`). The other is to use `doc(include)`: ```rust #![feature(external_doc)] #[doc(include = "lib.rs")] struct S {} ``` The first works, but is non-trivial for people to discover, and difficult to read and maintain. The second is a strange special-case for a particular use of the macro. This generalizes it to work for any use case, not just including files. I plan to remove `doc(include)` when this is stabilized (rust-lang#82539). The `forward_inner_docs` workaround will still compile without warnings, but I expect it to be used less once it's no longer necessary.
Merged
jackh726
added a commit
to jackh726/rust
that referenced
this pull request
May 19, 2021
…=petrochenkov Stabilize extended_key_value_attributes Closes rust-lang#44732. Closes rust-lang#78835. Closes rust-lang#82768 (by making it irrelevant). # Stabilization report ## Summary This stabilizes using macro expansion in key-value attributes, like so: ```rust #[doc = include_str!("my_doc.md")] struct S; #[path = concat!(env!("OUT_DIR"), "/generated.rs")] mod m; ``` See Petrochenkov's excellent blog post [on internals](https://internals.rust-lang.org/t/macro-expansion-points-in-attributes/11455) for alternatives that were considered and rejected ("why accept no more and no less?") This has been available on nightly since 1.50 with no major issues. ## Notes ### Accepted syntax The parser accepts arbitrary Rust expressions in this position, but any expression other than a macro invocation will ultimately lead to an error because it is not expected by the built-in expression forms (e.g., `#[doc]`). Note that decorators and the like may be able to observe other expression forms. ### Expansion ordering Expansion of macro expressions in "inert" attributes occurs after decorators have executed, analogously to macro expressions appearing in the function body or other parts of decorator input. There is currently no way for decorators to accept macros in key-value position if macro expansion must be performed before the decorator executes (if the macro can simply be copied into the output for later expansion, that can work). ## Test cases - https://github.com/rust-lang/rust/blob/master/src/test/ui/attributes/key-value-expansion-on-mac.rs - https://github.com/rust-lang/rust/blob/master/src/test/rustdoc/external-doc.rs The feature has also been dogfooded extensively in the compiler and standard library: - rust-lang#83329 - rust-lang#83230 - rust-lang#82641 - rust-lang#80534 ## Implementation history - Initial proposal: rust-lang#55414 (comment) - Experiment to see how much code it would break: rust-lang#67121 - Preliminary work to restrict expansion that would conflict with this feature: rust-lang#77271 - Initial implementation: rust-lang#78837 - Fix for an ICE: rust-lang#80563 ## Unresolved Questions ~~rust-lang#83366 (comment) listed some concerns, but they have been resolved as of this final report.~~ ## Additional Information There are two workarounds that have a similar effect for `#[doc]` attributes on nightly. One is to emulate this behavior by using a limited version of this feature that was stabilized for historical reasons: ```rust macro_rules! forward_inner_docs { ($e:expr => $i:item) => { #[doc = $e] $i }; } forward_inner_docs!(include_str!("lib.rs") => struct S {}); ``` This also works for other attributes (like `#[path = concat!(...)]`). The other is to use `doc(include)`: ```rust #![feature(external_doc)] #[doc(include = "lib.rs")] struct S {} ``` The first works, but is non-trivial for people to discover, and difficult to read and maintain. The second is a strange special-case for a particular use of the macro. This generalizes it to work for any use case, not just including files. I plan to remove `doc(include)` when this is stabilized (rust-lang#82539). The `forward_inner_docs` workaround will still compile without warnings, but I expect it to be used less once it's no longer necessary.
bors
added a commit
to rust-lang-ci/rust
that referenced
this pull request
Jun 5, 2021
…eGomez Remove `doc(include)` This nightly feature is redundant now that `extended_key_value_attributes` is stable (rust-lang#83366). `@rust-lang/rustdoc` not sure if you think this needs FCP; there was already an FCP in rust-lang#82539, but technically it was for deprecating, not removing the feature altogether. This should not be merged before rust-lang#83366. cc `@petrochenkov`
isislovecruft
added a commit
to isislovecruft/subtle
that referenced
this pull request
Jul 13, 2021
The latest rust nightlies and beta (at stable version 1.55) include a
change from
#![cfg_attr(feature = "nightly", feature(external_doc))]
#![cfg_attr(feature = "nightly", doc(include = "../README.md"))]
to removing `feature(external_doc)` and also changing the syntax of
the second line to
#![cfg_attr(feature = "nightly", doc = include_str!("../README.md"))]
However. `include_str!` is stable currently, but the syntax of `doc =
` is expressly disallowed. This gives me four options:
1. Don't build documentation (bad)
2. Copy-pasta README.md into src/lib.rs (also bad)
3. Support only beta/nightly but not stable (completely untennable
for a crate with ~14 million downloads)
4. Support only stable but not beta/nightly (also untennable)
Further, waiting for this to be "fixed" by its inclusion in stable
Rust in about a week means that our MSRV increases from 1.41 to 1.56,
with no changes to actual code (other than how to build documentation)
at all, which seems quite unfriendly to downstream dependents who are
pinning their rust versions for whatever reason.
So, sadly, it seems the most friendly fix is to copy-pasta our
README.md into the codebase.
(cf. rust-lang/rust#44732,
rust-lang/rust#82539)
isislovecruft
added a commit
to isislovecruft/subtle
that referenced
this pull request
Jul 13, 2021
The latest rust nightlies and beta (at stable version 1.55) include a
change from
#![cfg_attr(feature = "nightly", feature(external_doc))]
#![cfg_attr(feature = "nightly", doc(include = "../README.md"))]
to removing `feature(external_doc)` and also changing the syntax of
the second line to
#![cfg_attr(feature = "nightly", doc = include_str!("../README.md"))]
However. `include_str!` is stable currently, but the syntax of `doc =
` is expressly disallowed. This gives me four options:
1. Don't build documentation (bad)
2. Copy-pasta README.md into src/lib.rs (also bad)
3. Support only beta/nightly but not stable (completely untennable
for a crate with ~14 million downloads)
4. Support only stable but not beta/nightly (also untennable)
Further, waiting for this to be "fixed" by its inclusion in stable
Rust in about a week means that our MSRV increases from 1.41 to 1.56,
with no changes to actual code (other than how to build documentation)
at all, which seems quite unfriendly to downstream dependents who are
pinning their rust versions for whatever reason.
So, sadly, it seems the most friendly fix is to copy-pasta our
README.md into the codebase.
(cf. rust-lang/rust#44732,
rust-lang/rust#82539)
thedodd
added a commit
to thedodd/ybc
that referenced
this pull request
Jul 26, 2021
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.
Why deprecate doc(include)?
This nightly feature is a strictly less general version of
extended_key_value_attributes(#78835), which looks like this:In particular, that feature allows manipulating the filename and
included docs in a way that
doc(include)cannot, due to eagerevaluation:
For more about eager evaluation and how it impacts macro parsing,
see petrochenkov's excellent writeup: https://internals.rust-lang.org/t/macro-expansion-points-in-attributes/11455
Given that
#[doc(include)]offers no features thatextended_key_value_attributescannot, it makes no sense for thelanguage and rustdoc to maintain it indefinitely. This deprecates
doc(include)and adds a structured suggestion to switch to switch todoc = include_str!instead.Implementation
This now adds a
DOC_INCLUDElint, which is marked asfuture_incompatible. To make that possible, it also extendsdeclare_tool_lint!anddeclare_rustdoc_lint!to allow future-incompat lints. Finally, it changesAttributes::from_astto require anOption<HirId>instead of just whether the item is local or not.cc #44732. I plan to remove the feature gate altogether eventually, but I want to have at least a month or two when it's deprecated so people have time to switch.
r? @GuillaumeGomez cc @petrochenkov