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

Document doc(keyword) unstable attribute #90398

Merged
merged 1 commit into from
Nov 1, 2021
Merged

Document doc(keyword) unstable attribute #90398

merged 1 commit into from
Nov 1, 2021

Conversation

GuillaumeGomez
Copy link
Member

@GuillaumeGomez 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 rust-highfive added the S-waiting-on-review Status: Awaiting review from the assignee but also interested parties. label Oct 29, 2021
@rust-log-analyzer

This comment has been minimized.

Sign in to view
camelid
camelid requested changes Oct 29, 2021
View reviewed changes
Copy link
Member

@camelid camelid left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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."

src/doc/rustdoc/src/unstable-features.md Outdated Show resolved Hide resolved
src/doc/rustdoc/src/unstable-features.md Outdated Show resolved Hide resolved
src/doc/rustdoc/src/unstable-features.md Outdated Show resolved Hide resolved
@camelid
Copy link
Member

camelid commented Oct 29, 2021

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

@GuillaumeGomez
Copy link
Member Author

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
Copy link
Member

camelid commented Oct 29, 2021

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
Copy link
Member

camelid commented Oct 29, 2021

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.

@camelid camelid added S-waiting-on-team Status: Awaiting decision from the relevant subteam (see the T-<team> label). and removed S-waiting-on-review Status: Awaiting review from the assignee but also interested parties. labels Oct 30, 2021
@Manishearth
Copy link
Member

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
Copy link
Member Author

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. :)

@GuillaumeGomez GuillaumeGomez mentioned this pull request Oct 30, 2021
Merged
@camelid 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 Status: Awaiting decision from the relevant subteam (see the T-<team> label). labels Oct 30, 2021
@GuillaumeGomez 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
camelid reviewed Oct 30, 2021
View reviewed changes
Copy link
Member

@camelid camelid left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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?

src/doc/rustdoc/src/unstable-features.md Outdated Show resolved Hide resolved
src/doc/rustdoc/src/unstable-features.md Outdated Show resolved Hide resolved
@camelid 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
Copy link
Member Author

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
Copy link
Member

jyn514 commented Oct 30, 2021

@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
Copy link
Member Author

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

@jyn514
Copy link
Member

jyn514 commented Oct 30, 2021

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

@GuillaumeGomez
Copy link
Member Author

Fine, fine...

@GuillaumeGomez
Copy link
Member Author

Done.

@camelid camelid changed the title Add doc about doc(keyword) unstable attribute Document doc(keyword) unstable attribute Oct 30, 2021
camelid
camelid reviewed Oct 30, 2021
View reviewed changes
Copy link
Member

@camelid camelid left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

r=me with the following three comments addressed

src/doc/rustdoc/src/unstable-features.md Outdated Show resolved Hide resolved
src/doc/rustdoc/src/unstable-features.md Outdated Show resolved Hide resolved
@GuillaumeGomez
Copy link
Member Author

@bors: r=camelid rollup

@bors
Copy link
Contributor

bors commented Oct 31, 2021

📌 Commit 7bea8ea has been approved by camelid

@bors 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
@matthiaskrgr
Rollup merge of rust-lang#90398 - GuillaumeGomez:doc-keyword-doc, r=c…
9f4fd67 
…amelid

Document `doc(keyword)` unstable attribute

r? `@camelid`
@matthiaskrgr matthiaskrgr mentioned this pull request Oct 31, 2021
Closed
@matthiaskrgr matthiaskrgr mentioned this pull request Nov 1, 2021
Merged
bors added a commit to rust-lang-ci/rust that referenced this pull request Nov 1, 2021
@bors
Auto merge of rust-lang#90463 - matthiaskrgr:rollup-eljk9vo, r=matthi…
e9b0d99 
…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
@bors bors merged commit 0b8d3b1 into rust-lang:master Nov 1, 2021
@rustbot rustbot added this to the 1.58.0 milestone Nov 1, 2021
@GuillaumeGomez GuillaumeGomez deleted the doc-keyword-doc branch November 1, 2021 17:54
GuillaumeGomez added a commit to GuillaumeGomez/rust that referenced this pull request Nov 24, 2021
@GuillaumeGomez
Rollup merge of rust-lang#90420 - GuillaumeGomez:rustdoc-internals-fe…
f52f0e5 
…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 a commit to GuillaumeGomez/rust that referenced this pull request Nov 24, 2021
@GuillaumeGomez
Rollup merge of rust-lang#90420 - GuillaumeGomez:rustdoc-internals-fe…
a6a1d7c 
…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`` ?
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Reviewers

@camelid camelid camelid requested changes

@Manishearth Manishearth Manishearth left review comments

Assignees

@camelid camelid

Labels
A-docs Area: documentation for any part of the project, including the compiler, standard library, and tools S-waiting-on-bors Status: Waiting on bors to run and complete tests. Bors will change the label on completion. T-rustdoc Relevant to the rustdoc team, which will review and decide on the PR/issue.
Projects
None yet
Milestone
1.58.0
Development

Successfully merging this pull request may close these issues.
8 participants
@GuillaumeGomez @rust-log-analyzer @camelid @Manishearth @jyn514 @bors @rust-highfive @rustbot