Document `doc(keyword)` unstable attribute by GuillaumeGomez · Pull Request #90398 · rust-lang/rust

GuillaumeGomez · 2021-10-29T12:49:53Z

camelid

I don't think we should be documenting #[doc(keyword)] and #[doc(primitive)] beyond saying, "They're permanently unstable and only meant to be used by the standard library."

camelid · 2021-10-29T20:31:09Z

cc @rust-lang/rustdoc for discussion about whether we should be documenting #[doc(keyword)], and if so, to what extent.

GuillaumeGomez · 2021-10-29T20:32:12Z

I don't think we should be documenting #[doc(keyword)] and #[doc(primitive)] beyond saying, "They're permanently unstable and only meant to be used by the standard library."

Except that if you use macro and proc-macro, you might want to add new keywords. Wouldn't it make sense to document them then? I still think that this feature should get stabilized at some point.

camelid · 2021-10-29T23:07:12Z

I don't think we should be documenting #[doc(keyword)] and #[doc(primitive)] beyond saying, "They're permanently unstable and only meant to be used by the standard library."
Except that if you use macro and proc-macro, you might want to add new keywords. Wouldn't it make sense to document them then? I still think that this feature should get stabilized at some point.

The "keywords" in macros that you are describing are not really keywords; they are limited to the scope of the macro invocation. Outside of an invocation of that macro, they are not keywords. As @Manishearth said, custom macro keywords should be documented in the macro itself, not using #[doc(keyword)].

camelid · 2021-10-29T23:07:25Z

In some ways, I wonder if it would make sense for us to put #[doc(primitive)] and #[doc(keyword)] behind the same feature gate, named something like rustdoc_internals. That would underscore that the attributes are more like implementation details.

Manishearth · 2021-10-30T04:47:42Z

Right, macros can't actually add new keywords, they can in their own context parse identifiers in a way that may seem keywordlike. Which can be documented on the macro itself.

GuillaumeGomez · 2021-10-30T10:58:47Z

That makes sense. I'll reword the documentation then!

@camelid Putting them behind the same feature would make sense. I'll send a PR for that. :)

camelid

Two nits, but also: wasn't the plan to change the docs here so they make it clear that these attributes are for internal use only? Or were you going to do that in the rustdoc_internals PR?

GuillaumeGomez · 2021-10-30T20:12:21Z

Two nits, but also: wasn't the plan to change the docs here so they make it clear that these attributes are for internal use only?

We don't know what the future will be made of. Maybe we will allow to create new keywords in the future? Who knows? At least now, we simply explain how we do it in the standard library and that's it.

Fixing the two nits quickly.

jyn514 · 2021-10-30T20:13:13Z

@GuillaumeGomez if we change our minds in the future, we can change the documentation at the same time. For now I think we should make it clear that these aren't intended to be stabilized.

GuillaumeGomez · 2021-10-30T20:16:32Z

We didn't say so anywhere else as far as I can see, so seems weird to start it now...

jyn514 · 2021-10-30T20:20:55Z

@GuillaumeGomez the whole point of #90420 is that these are not intended to be used by anyone other than the standard library.

GuillaumeGomez · 2021-10-30T20:23:29Z

Fine, fine...

GuillaumeGomez · 2021-10-30T20:24:43Z

Done.

camelid

r=me with the following three comments addressed

GuillaumeGomez · 2021-10-31T12:57:35Z

@bors: r=camelid rollup

bors · 2021-10-31T12:57:36Z

📌 Commit 7bea8ea has been approved by camelid

…amelid Document `doc(keyword)` unstable attribute r? `@camelid`

…askrgr Rollup of 8 pull requests Successful merges: - rust-lang#89826 (Feature gate + make must_not_suspend allow-by-default) - rust-lang#89929 (Handling submodule update failures more gracefully from x.py) - rust-lang#90333 (rustdoc: remove flicker during page load) - rust-lang#90349 (Fix rare ICE during typeck in rustdoc scrape_examples) - rust-lang#90398 (Document `doc(keyword)` unstable attribute) - rust-lang#90441 (Test that promotion follows references when looking for drop) - rust-lang#90450 (Remove `rustc_hir::hir_id::HirIdVec`) - rust-lang#90452 (Remove unnecessary `Option` from `promote_candidate` return type) Failed merges: r? `@ghost` `@rustbot` modify labels: rollup

…ature, r=camelid Create rustdoc_internals feature gate As suggested by `@camelid` [here](rust-lang#90398 (comment)), since `doc_keyword` and `doc_primitive` aren't meant to be stabilized, we could put them behind a same feature flag. This is pretty much what it would look like (needs to update the tests too). The tracking issue is rust-lang#90418. What do you think `@rust-lang/rustdoc` ?

…ature, r=camelid Create rustdoc_internals feature gate As suggested by ``@camelid`` [here](rust-lang#90398 (comment)), since `doc_keyword` and `doc_primitive` aren't meant to be stabilized, we could put them behind a same feature flag. This is pretty much what it would look like (needs to update the tests too). The tracking issue is rust-lang#90418. What do you think ``@rust-lang/rustdoc`` ?

GuillaumeGomez added T-rustdoc Relevant to the rustdoc team, which will review and decide on the PR/issue. A-docs Area: Documentation for any part of the project, including the compiler, standard library, and tools labels Oct 29, 2021

rust-highfive assigned camelid Oct 29, 2021

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

This comment has been minimized.
Sign in to view

GuillaumeGomez force-pushed the doc-keyword-doc branch from a2260c2 to 2ecc67bCompare October 29, 2021 13:45

camelid requested changes Oct 29, 2021
View reviewed changes

Comment threadsrc/doc/rustdoc/src/unstable-features.md Outdated
Comment threadsrc/doc/rustdoc/src/unstable-features.md Outdated
Comment threadsrc/doc/rustdoc/src/unstable-features.md Outdated

camelid added S-waiting-on-team and removed S-waiting-on-review Status: Awaiting review from the assignee but also interested parties. labels Oct 30, 2021

GuillaumeGomez mentioned this pull request Oct 30, 2021
Create rustdoc_internals feature gate #90420
Merged

camelid 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-team labels Oct 30, 2021

GuillaumeGomez force-pushed the doc-keyword-doc branch from 2ecc67b to 2813fc9Compare October 30, 2021 20:05

GuillaumeGomez 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 Oct 30, 2021

camelid reviewed Oct 30, 2021
View reviewed changes

Comment threadsrc/doc/rustdoc/src/unstable-features.md Outdated
Comment threadsrc/doc/rustdoc/src/unstable-features.md Outdated

camelid 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 Oct 30, 2021

GuillaumeGomez force-pushed the doc-keyword-doc branch from 2813fc9 to 075e2f6Compare October 30, 2021 20:13

GuillaumeGomez force-pushed the doc-keyword-doc branch from 075e2f6 to c060896Compare October 30, 2021 20:24

camelid changed the title ~~Add doc about doc(keyword) unstable attribute~~Document doc(keyword) unstable attributeOct 30, 2021

camelid reviewed Oct 30, 2021
View reviewed changes

Comment threadsrc/doc/rustdoc/src/unstable-features.md Outdated
Comment threadsrc/doc/rustdoc/src/unstable-features.md Outdated

Add doc about doc(keyword) unstable attribute
7bea8ea

GuillaumeGomez force-pushed the doc-keyword-doc branch from c060896 to 7bea8eaCompare October 31, 2021 12:57

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-author Status: This is awaiting some action (such as code changes or more information) from the author. labels Oct 31, 2021

matthiaskrgr added a commit to matthiaskrgr/rust that referenced this pull request Oct 31, 2021
Rollup merge ofrust-lang#90398- GuillaumeGomez:doc-keyword-doc, r=c…
9f4fd67
…amelid Document `doc(keyword)` unstable attribute r? `@camelid`

matthiaskrgr mentioned this pull request Oct 31, 2021
Rollup of 5 pull requests #90458
Closed

matthiaskrgr mentioned this pull request Nov 1, 2021
Rollup of 8 pull requests #90463
Merged

bors merged commit 0b8d3b1 into rust-lang:masterNov 1, 2021

rustbot added this to the 1.58.0 milestone Nov 1, 2021

GuillaumeGomez deleted the doc-keyword-doc branch November 1, 2021 17:54

Uh oh!

Uh oh!

Conversation

GuillaumeGomez commented Oct 29, 2021

Uh oh!

This comment has been minimized.

camelid left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

camelid commented Oct 29, 2021

Uh oh!

GuillaumeGomez commented Oct 29, 2021

Uh oh!

camelid commented Oct 29, 2021

Uh oh!

camelid commented Oct 29, 2021

Uh oh!

Manishearth commented Oct 30, 2021

Uh oh!

GuillaumeGomez commented Oct 30, 2021

Uh oh!

camelid left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

GuillaumeGomez commented Oct 30, 2021

Uh oh!

jyn514 commented Oct 30, 2021

Uh oh!

GuillaumeGomez commented Oct 30, 2021

Uh oh!

jyn514 commented Oct 30, 2021

Uh oh!

GuillaumeGomez commented Oct 30, 2021

Uh oh!

GuillaumeGomez commented Oct 30, 2021

Uh oh!

camelid left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

GuillaumeGomez commented Oct 31, 2021

Uh oh!

bors commented Oct 31, 2021

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

8 participants