Improve lang item generated docs #82641

camelid · 2021-02-28T19:44:48Z

camelid · 2021-02-28T19:47:37Z

I was getting seemingly-unrelated errors when running x.py doc before (see this Zulip thread), so part of why I'm opening the PR is to see if CI passes. (Does CI even run x.py doc compiler/rustc?)

jyn514 · 2021-02-28T19:54:06Z

compiler/rustc_hir/src/lang_items.rs

@@ -103,13 +109,13 @@ macro_rules! language_item_table {
                self.items[it as usize].ok_or_else(|| format!("requires `{}` lang_item", it.name()))
            }

+            /// Returns the [`DefId`]s of all lang items in a group.


Does this include language items that aren't in the current crate?

Given #82641 (comment), I would assume yes.

Ok, can you add that as a comment?

I can, but it seems redundant given that we say

Defined lang items can come from the current crate or its dependencies.

at the top of the docs. If you still think I should add a comment, could you suggest what you want it to say so we're on the same page?

Ah ok, I missed that comment.

compiler/rustc_hir/src/lang_items.rs

camelid · 2021-02-28T21:44:01Z

Hmm, not quite right:

I'm not sure if there's a good way to fix this though. I thought of removing the explicit sym:: but some of the lang items use kw::. Another option would be to store a static string for each pre-declared symbol (like kw::Fn and sym::eq). I think that would work but the use case doesn't seem worth the semi-significant changes (and I don't really feel like touching the symbols! proc macro ^^). Yet another option would be to somehow strip off the leading sym:: or kw:: for docs, but that seems like it would require messing with syn and quote.

On the other hand, it doesn't look too bad the way it is now =). We could also add an intra-doc link to the symbol for each one, but I'm not sure if that would help.

compiler/rustc_hir/src/lang_items.rs

It needs to be a variable! Co-authored-by: Joshua Nelson <joshua@yottadb.com>

compiler/rustc_hir/src/lang_items.rs

jyn514 · 2021-03-10T18:47:05Z

r=me with #82641 (comment) addressed, this is great!

jyn514 · 2021-03-11T04:38:55Z

@bors r+

bors · 2021-03-11T04:38:56Z

📌 Commit ab42f96 has been approved by jyn514

bors · 2021-03-11T06:38:26Z

⌛ Testing commit ab42f96 with merge 04fce73...

bors · 2021-03-11T09:08:49Z

☀️ Test successful - checks-actions
Approved by: jyn514
Pushing 04fce73 to master...

# 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 the changes to the reference for details on what macros are allowed; 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. The `forward_inner_docs` workaround will still compile without warnings, but I expect it to be used less once it's no longer necessary.

…=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.

Improve lang item generated docs

e5f1e88

cc https://rust-lang.zulipchat.com/#narrow/stream/146229-wg-secure-code/topic/Is.20.60core.60.20part.20of.20the.20compiler.3F/near/226738260

rust-highfive assigned jyn514 Feb 28, 2021

rust-highfive added the S-waiting-on-review Status: Awaiting review from the assignee but also interested parties. label Feb 28, 2021

This comment has been minimized.

Sign in to view

Allow variant attributes in enum_from_u32!

58758f0

jyn514 reviewed Feb 28, 2021

View reviewed changes

Enable extended_key_value_attributes in rustc_hir

da0099a

This comment has been minimized.

Sign in to view

Convert some lang item comments to doc-comments

4b3490f

camelid force-pushed the lang-item-docs branch from 46be4bc to 4b3490f Compare February 28, 2021 20:05

This comment has been minimized.

Sign in to view

camelid commented Feb 28, 2021

View reviewed changes

compiler/rustc_hir/src/lang_items.rs Outdated Show resolved Hide resolved

petrochenkov mentioned this pull request Feb 28, 2021

expand: Refactor module loading #82415

Merged

camelid commented Feb 28, 2021

View reviewed changes

compiler/rustc_hir/src/lang_items.rs Outdated Show resolved Hide resolved

jyn514 reviewed Mar 10, 2021

View reviewed changes

compiler/rustc_hir/src/lang_items.rs Outdated Show resolved Hide resolved

compiler/rustc_hir/src/lang_items.rs Outdated Show resolved Hide resolved

compiler/rustc_hir/src/lang_items.rs Outdated Show resolved Hide resolved

compiler/rustc_hir/src/lang_items.rs Outdated Show resolved Hide resolved

camelid added the A-docs Area: Documentation for any part of the project, including the compiler, standard library, and tools label Mar 10, 2021

Fix bug

4900836

It needs to be a variable! Co-authored-by: Joshua Nelson <joshua@yottadb.com>

camelid force-pushed the lang-item-docs branch from 0bec790 to 7146aeb Compare March 10, 2021 17:06

This comment has been minimized.

Sign in to view

jyn514 reviewed Mar 10, 2021

View reviewed changes

compiler/rustc_hir/src/lang_items.rs Outdated Show resolved Hide resolved

Remove sym:: and kw:: from generated docs

b782939

jyn514 added S-waiting-on-author Status: This is awaiting some action (such as code changes or more information) from the author. and removed S-waiting-on-review Status: Awaiting review from the assignee but also interested parties. labels Mar 10, 2021

camelid added S-waiting-on-review Status: Awaiting review from the assignee but also interested parties. and removed S-waiting-on-author Status: This is awaiting some action (such as code changes or more information) from the author. labels Mar 11, 2021

bors added S-waiting-on-bors Status: Waiting on bors to run and complete tests. Bors will change the label on completion. and removed S-waiting-on-review Status: Awaiting review from the assignee but also interested parties. labels Mar 11, 2021

bors added the merged-by-bors This PR was explicitly merged by bors. label Mar 11, 2021

bors merged commit 04fce73 into rust-lang:master Mar 11, 2021

rustbot added this to the 1.52.0 milestone Mar 11, 2021

camelid deleted the lang-item-docs branch March 11, 2021 18:28

jyn514 mentioned this pull request Mar 22, 2021

Stabilize extended_key_value_attributes #83366

Merged

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Improve lang item generated docs #82641

Improve lang item generated docs #82641

camelid commented Feb 28, 2021 •

edited

Loading

camelid commented Feb 28, 2021

This comment has been minimized.

jyn514 Feb 28, 2021

camelid Mar 10, 2021

jyn514 Mar 10, 2021

camelid Mar 11, 2021 •

edited

Loading

jyn514 Mar 11, 2021

This comment has been minimized.

This comment has been minimized.

camelid commented Feb 28, 2021

This comment has been minimized.

jyn514 commented Mar 10, 2021

jyn514 commented Mar 11, 2021

bors commented Mar 11, 2021

bors commented Mar 11, 2021

bors commented Mar 11, 2021

Improve lang item generated docs #82641

Improve lang item generated docs #82641

Conversation

camelid commented Feb 28, 2021 • edited Loading

camelid commented Feb 28, 2021

This comment has been minimized.

jyn514 Feb 28, 2021

Choose a reason for hiding this comment

camelid Mar 10, 2021

Choose a reason for hiding this comment

jyn514 Mar 10, 2021

Choose a reason for hiding this comment

camelid Mar 11, 2021 • edited Loading

Choose a reason for hiding this comment

jyn514 Mar 11, 2021

Choose a reason for hiding this comment

This comment has been minimized.

This comment has been minimized.

camelid commented Feb 28, 2021

This comment has been minimized.

jyn514 commented Mar 10, 2021

jyn514 commented Mar 11, 2021

bors commented Mar 11, 2021

bors commented Mar 11, 2021

bors commented Mar 11, 2021

camelid commented Feb 28, 2021 •

edited

Loading

camelid Mar 11, 2021 •

edited

Loading