Add identifiers to attributes.md and its subchapters #1560

chorman0773 · 2024-08-06T17:15:43Z

This adds identifiers to the attributes.md file and its subchapters, being:

attributes/codegen.md
attributes/debugging.md
attributes/derive.md
attributes/diagnostics.md
attributes/limits.md
attributes/testing.md
attributes/type_system.md

ehuss · 2024-09-04T20:19:37Z

src/attributes.md

@@ -15,29 +16,32 @@
 > &nbsp;&nbsp; &nbsp;&nbsp; [_DelimTokenTree_]\
 > &nbsp;&nbsp; | `=` [_Expression_]

+r[attributes.general]


Here and all elsewhere.

Suggested change

r[attributes.general]

r[attributes.intro]

(As an aside, I wonder if definition might fit these kinds of paragraphs better. We should probably define our common terms so that we understand when to use them appropriately.)

ehuss · 2024-09-04T20:21:31Z

src/attributes/codegen.md

 When applied to a function in an `extern` block the attribute must also be applied to any linked
 implementations, otherwise undefined behavior results. When applied to a function which is made
 available to an `extern` block, the declaration in the `extern` block must also have the attribute,
 otherwise undefined behavior results.

 ### Behavior

+r[attributes.codegen.track_caller.behaviour]


Here and elsewhere

Suggested change

r[attributes.codegen.track_caller.behaviour]

r[attributes.codegen.track_caller.behavior]

ehuss · 2024-09-04T20:21:53Z

src/attributes/codegen.md

@@ -397,8 +439,12 @@ And so on.

 ### Limitations

+r[attributes.codegen.track_caller.limits]
+
+r[attributes.codegent.track_caller.hint]


Please be careful about spelling.

Suggested change

r[attributes.codegent.track_caller.hint]

r[attributes.codegen.track_caller.hint]

ehuss · 2024-09-04T20:22:13Z

src/attributes/codegen.md

 Both attributes can be used on [functions]. When applied to a function in a
 [trait], they apply only to that function when used as a default function for
 a trait implementation and not to all trait implementations. The attributes
 have no effect on a trait function without a body.

 ### The `inline` attribute

+r[attributes.codgen.inline]


Suggested change

r[attributes.codgen.inline]

r[attributes.codegen.inline]

ehuss · 2024-09-04T20:22:32Z

src/attributes/diagnostics.md

 The *`deprecated` attribute* marks an item as deprecated. `rustc` will issue
 warnings on usage of `#[deprecated]` items. `rustdoc` will show item
 deprecation, including the `since` version and `note`, if available.

+r[attributes.diagnostics.deprectead.syntax]


Suggested change

r[attributes.diagnostics.deprectead.syntax]

r[attributes.diagnostics.deprecated.syntax]

ehuss · 2024-09-04T22:08:16Z

src/attributes/debugger.md

 It uses the [_MetaListNameValueStr_] syntax to specify its inputs, and must be specified as a crate attribute.

 ### Using `debugger_visualizer` with Natvis

+r[attributes.debugger.debugger_visualizer.natvis]
+
+r[attributes.debugger.debugger_visualizer.natvis-general]


Any particular reason to use - and not . for nativis-general?

ehuss · 2024-09-04T22:08:52Z

src/attributes/derive.md

+r[attributes.derive]
+
+
+r[attributes.derived.general]


Suggested change

r[attributes.derived.general]

r[attributes.derive.general]

ehuss · 2024-09-04T22:14:13Z

src/attributes/diagnostics.md

@@ -390,6 +432,7 @@ impl Trait for i32 {
 5i32.use_me();
 ```

+r[attributes.diagnostics.must_use.impl-function]


To distinguish from other non-trait impl, maybe?

Suggested change

r[attributes.diagnostics.must_use.impl-function]

r[attributes.diagnostics.must_use.trait-impl-function]

ehuss · 2024-09-04T22:19:10Z

src/attributes/diagnostics.md

@@ -424,36 +467,59 @@ When used on a function in a trait implementation, the attribute does nothing.

 ## The `diagnostic` tool attribute namespace

+r[attributes.diagnostics.namespace]


Hm, I'm on the fence here, since the namespace is singular diagnostic. I realize this is in the "diagnostics" section, and being inconsistent with the rest of the section could be more trouble. I'm just a little concerned about seeing diagnostics.namespace could confuse a reader, since it is a subtle distinction. WDYT?

I'm thinking the section should be changed to diagnostic because I've been otherwise favouring the singular form except for lists and when the construct is plural in the language.

ehuss · 2024-09-04T22:20:30Z

src/attributes/limits.md

 The following [attributes] affect compile-time limits.

 ## The `recursion_limit` attribute

+r[attributes.limits.recursion_limits]


Here and elsewhere.

Suggested change

r[attributes.limits.recursion_limits]

r[attributes.limits.recursion_limit]

chorman0773 · 2024-09-12T14:56:39Z

I need to modify the identifiers to be more consistent with the other chapters, and the guidelines I wrote.

@rustbot modify-labels +S-waiting-on-author -S-waiting-on-review

traviscross · 2024-10-17T23:41:20Z

@rustbot labels +S-waiting-on-author -S-waiting-on-review

The CI is failing on this one.

chorman0773 · 2024-10-21T16:27:02Z

@rustbot labels +S-waiting-on-review -S-waiting-on-author

This is just for navigation, these aren't specific rules.

ehuss

Thanks!

These are some misc rule name changes. Some of them are to give the rules more specific names (indicating what they do, instead of using generic terms). The `allowed-positions` name is intended to be used for all attributes to have a specific rule that defines where an attribute may be used. It is not consistently used, yet. Also, some of the paragraphs mix "where it goes" with "what it does" that should probably be teased apart so that we can label those independently. I expect us to do some more cleanup to bring some consistency to the attribute rules since there are a lot of attributes, and they generally have the same requirements of what needs to be specified.

This is keeping in line with using plurals throughout the rest of the naming convention. This also differentiates it from the `diagnostic` namespace. The `diagnostic` namespace remains singular, and is not nested with the plural `diagnostics` just to avoid the repetition.

chorman0773 added S-waiting-on-review Status: The marked PR is awaiting review from the PR author. T-spec Team: spec labels Aug 6, 2024

chorman0773 mentioned this pull request Aug 6, 2024

Tracking Issue: Adding mdbook-spec identifiers to reference chapters #1561

Open

90 tasks

ehuss reviewed Sep 4, 2024

View reviewed changes

chorman0773 added S-waiting-on-author Status: The marked PR is awaiting some action (such as code changes) from the PR author. and removed S-waiting-on-review Status: The marked PR is awaiting review from the PR author. labels Sep 12, 2024

chorman0773 added 12 commits October 21, 2024 12:20

Add identifier syntax to attributes.md

173a829

Add identifier syntax to attributes.codegen

e5acdc2

Add identifier syntax to attributes.debugger

41fe211

Add identifier syntax to attributes.derive

3b6ebe1

Add identifier syntax to attributes.diagnostics

42fbf9b

Add identifier syntax to attributes.limits

8f980cb

Add identifier syntax to attributes.testing

0657657

Add identifier syntax to attributes.type_system

2b5d973

Fix style in modified chapters

043c99f

Appease link-checker

b1a26cc

Apply suggestions from PR review

aa93e94

Replace uses of constraint and restriction in attributes chapters.

d3ef277

chorman0773 force-pushed the spec-add-identifiers-attributes branch from e579b2a to d3ef277 Compare October 21, 2024 16:20

rustbot added S-waiting-on-review Status: The marked PR is awaiting review from the PR author. and removed S-waiting-on-author Status: The marked PR is awaiting some action (such as code changes) from the PR author. labels Oct 21, 2024

ehuss added 4 commits November 15, 2024 13:25

Fix various spelling and format errors

ccbc70d

Add back some newlines that were removed

e0f31a0

Remove some double blank lines

da65af0

Remove annotations from the attribute index

b62fbd2

This is just for navigation, these aren't specific rules.

ehuss approved these changes Nov 15, 2024

View reviewed changes

ehuss force-pushed the spec-add-identifiers-attributes branch from 94aa44f to 4ef5f5d Compare November 15, 2024 21:42

ehuss enabled auto-merge November 15, 2024 21:43

ehuss added this pull request to the merge queue Nov 15, 2024

Merged via the queue into rust-lang:master with commit 41ccb0e Nov 15, 2024
5 checks passed

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Add identifiers to attributes.md and its subchapters #1560

Add identifiers to attributes.md and its subchapters #1560

chorman0773 commented Aug 6, 2024

ehuss Sep 4, 2024

ehuss Sep 4, 2024

ehuss Sep 4, 2024

ehuss Sep 4, 2024

ehuss Sep 4, 2024

ehuss Sep 4, 2024

ehuss Sep 4, 2024

ehuss Sep 4, 2024

ehuss Sep 4, 2024

chorman0773 Sep 6, 2024

ehuss Sep 4, 2024

chorman0773 commented Sep 12, 2024

traviscross commented Oct 17, 2024

chorman0773 commented Oct 21, 2024

ehuss left a comment

	r[attributes.codegen.track_caller.behaviour]
	r[attributes.codegen.track_caller.behavior]

	r[attributes.codegent.track_caller.hint]
	r[attributes.codegen.track_caller.hint]

	r[attributes.diagnostics.deprectead.syntax]
	r[attributes.diagnostics.deprecated.syntax]

	r[attributes.diagnostics.must_use.impl-function]
	r[attributes.diagnostics.must_use.trait-impl-function]

		@@ -424,36 +467,59 @@ When used on a function in a trait implementation, the attribute does nothing.

		## The `diagnostic` tool attribute namespace

		r[attributes.diagnostics.namespace]

	r[attributes.limits.recursion_limits]
	r[attributes.limits.recursion_limit]

		r[attributes.derive]


		r[attributes.derived.general]

Add identifiers to attributes.md and its subchapters #1560

Add identifiers to attributes.md and its subchapters #1560

Conversation

chorman0773 commented Aug 6, 2024

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

chorman0773 commented Sep 12, 2024

traviscross commented Oct 17, 2024

chorman0773 commented Oct 21, 2024

ehuss left a comment

Choose a reason for hiding this comment