Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

Deprecate doc(include) #82539

Closed
wants to merge 4 commits into from
Closed

Deprecate doc(include) #82539

wants to merge 4 commits into from

Commits on Apr 8, 2021

  1. Deprecate doc(include) 

     ## 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).
    @jyn514
    jyn514 committed Apr 8, 2021
    Configuration menu
    Copy the full SHA
    460d4ac View commit details
    Browse the repository at this point in the history

  2. Add DOC_INCLUDE lint

    @jyn514
    jyn514 committed Apr 8, 2021
    Configuration menu
    Copy the full SHA
    04f993f View commit details
    Browse the repository at this point in the history

  3. Pass a TyCtxt directly to Attribute::from_ast 

    This allows calling `tcx.struct_span_lint_hir` in the next commit. It
also slightly shortens the code.
    @jyn514
    jyn514 committed Apr 8, 2021
    Configuration menu
    Copy the full SHA
    53c4de3 View commit details
    Browse the repository at this point in the history

  4. Emit DOC_INCLUDE lint instead of a hard warning

    @jyn514
    jyn514 committed Apr 8, 2021
    Configuration menu
    Copy the full SHA
    98fcb6c View commit details
    Browse the repository at this point in the history