

Github Deprecate `doc(include)` by jyn514 · Pull Request #82539 · rust-lang/rust...
source link: https://github.com/rust-lang/rust/pull/82539
Go to the source link to view the article. You can view the picture content, updated content and better typesetting reading experience. If the link is broken, please click the button below to view the snapshot at that time.

Why deprecate doc(include)?
This nightly feature is a strictly less general version ofextended_key_value_attributes
(#78835), 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 thatextended_key_value_attributes
cannot, it makes no sense for the
language and rustdoc to maintain it indefinitely. This deprecatesdoc(include)
and adds a structured suggestion to switch to switch todoc = 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 #82284 for the
sort of trouble that can cause).
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
Recommend
-
11
Pass around Symbols instead of Idents in doctree #79623
-
10
Collaborator rust-log-analyzer commented
-
13
New issue Change error about unknown attributes to a warning #82702 C...
-
10
Copy link Member jyn514 commented
-
15
Make rustdoc lints a tool lint instead of built-in by jyn514 · Pull Request #80527 · rust-lang/rust · GitHub Copy link Member ...
-
12
Copy link Member jyn514 commented
-
17
Copy link Member jyn514 commented...
-
7
This comment has been hidden.
-
17
Conversation Copy link
-
8
Member
About Joyk
Aggregate valuable and interesting links.
Joyk means Joy of geeK