Github Deprecate `doc(include)` by jyn514 · Pull Request #82539 · rust-lang/rust...

jyn514 commented 17 days ago •

Why deprecate doc(include)?

This nightly feature is a strictly less general version of
extended_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 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 #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