Update for review comments.

- Various fixes.
- Move new pages to an `attributes` subdirectory.
- Add some introductory text to new pages.
- Remove "closure" from `cold` and `inline`, it is not stable.
- Remove TODOs.
- Added link for `feature`.

src/SUMMARY.md

@@ -40,8 +40,11 @@
     - [Visibility and Privacy](visibility-and-privacy.md)
 
 - [Attributes](attributes.md)
-    - [Derive](derive.md)
-    - [Compiler attributes](compiler-attrs.md)
+    - [Testing](attributes/testing.md)
+    - [Derive](attributes/derive.md)
+    - [Diagnostics](attributes/diagnostics.md)
+    - [Code generation](attributes/codegen.md)
+    - [Compiler settings](attributes/compiler-settings.md)
 
 - [Statements and expressions](statements-and-expressions.md)
     - [Statements](statements.md)
@@ -117,12 +120,6 @@
 
 - [The Rust runtime](runtime.md)
 
-- [Code generation](codegen.md)
-
-- [Testing](testing.md)
-
-- [Diagnostics](diagnostics.md)
-
 - [Appendices](appendices.md)
     - [Macro Follow-Set Ambiguity Formal Specification](macro-ambiguity.md)
     - [Influences](influences.md)

src/attributes-redirect.html

@@ -4,20 +4,20 @@
         "#cold-attribute": "codegen.html#the-cold-attribute",
         "#conditional-compilation": "conditional-compilation.html",
         "#deprecation": "diagnostics.html#the-deprecated-attribute",
-        "#derive": "derive.html",
+        "#derive": "attributes/derive.html",
         "#documentation": "../rustdoc/the-doc-attribute.html",
-        "#ffi-attributes": "attributes.html#built-in-attributes",
+        "#ffi-attributes": "attributes.html#built-in-attributes-index",
         "#inline-attribute": "codegen.html#the-inline-attribute",
         "#lint-check-attributes": "diagnostics.html#lint-check-attributes",
-        "#macro-related-attributes": "attributes.html#built-in-attributes",
-        "#miscellaneous-attributes": "attributes.html#built-in-attributes",
+        "#macro-related-attributes": "attributes.html#built-in-attributes-index",
+        "#miscellaneous-attributes": "attributes.html#built-in-attributes-index",
         "#must_use": "diagnostics.html#the-must_use-attribute",
         "#optimization-hints": "codegen.html#optimization-hints",
         "#path": "items/modules.html#the-path-attribute",
         "#preludes": "crates-and-source-files.html#preludes-and-no_std",
         "#testing": "testing.html",
         "#tool-lint-attributes": "diagnostics.html#tool-lint-attributes",
-        "#crate-only-attributes": "attributes.html#built-in-attributes",
+        "#crate-only-attributes": "attributes.html#built-in-attributes-index",
     };
     var target = fragments[window.location.hash];
     if (target) {

src/attributes.md

@@ -172,11 +172,11 @@ pub fn f() {}
 
 > Note: `rustc` currently recognizes the tools "clippy" and "rustfmt".
 
-## Built-in attributes
+## Built-in attributes index
 
 The following is an index of all built-in attributes.
 
-- Conditional Compilation
+- Conditional compilation
   - [`cfg`] — Controls conditional compilation.
   - [`cfg_attr`] — Conditionally includes attributes.
 - Testing
@@ -185,7 +185,6 @@ The following is an index of all built-in attributes.
   - [`should_panic`] — Indicates a test should generate a panic.
 - Derive
   - [`derive`] — Automatic trait implementations.
-  <!-- automatically_derived -->
 - Macros
   - [`macro_export`] — Exports a `macro_rules` macro for cross-crate usage.
   - [`macro_use`] — Expands macro visibility, or imports macros from other
@@ -197,7 +196,7 @@ The following is an index of all built-in attributes.
   - [`allow`], [`warn`], [`deny`], [`forbid`] — Alters the default lint level.
   - [`deprecated`] — Generates deprecation notices.
   - [`must_use`] — Generates a lint for unused values.
-- ABI, Linking, Symbols, and FFI
+- ABI, linking, symbols, and FFI
   - [`link`] — Specifies a native library to link with an `extern` block.
   - [`link_name`] — Specifies the name of the symbol for functions or statics
     in an `extern` block.
@@ -213,16 +212,15 @@ The following is an index of all built-in attributes.
   - [`used`] - Forces the compiler to keep a static variable in the output
     object file.
   - [`crate_name`] — Specifies the crate name.
-- Code Generation
+- Code generation
   - [`inline`] — Hint to inline code.
   - [`cold`] — Hint that a function is unlikely to be called.
   - [`no_builtins`] — Disables use of certain built-in functions.
-  <!-- target_feature -->
-- Compiler Settings
+- Compiler setting attributes
+  - `feature` — Used to enable unstable or experimental compiler features. See
+    [The Unstable Book] for features implemented in `rustc`.
   - [`recursion_limit`] — Sets the maximum recursion limit for certain
     compile-time operations.
-  <!-- feature -->
-  <!--type_length_limit -->
 - Documentation
   - `doc` — Specifies documentation. See [The Rustdoc Book] for more
     information. [Doc comments] are transformed into `doc` attributes.
@@ -244,31 +242,32 @@ The following is an index of all built-in attributes.
 [RAW_STRING_LITERAL]: tokens.html#raw-string-literals
 [STRING_LITERAL]: tokens.html#string-literals
 [The Rustdoc Book]: ../rustdoc/the-doc-attribute.html
+[The Unstable Book]: ../unstable-book/index.html
 [_DelimTokenTree_]: macros.html
 [_LiteralExpression_]: expressions/literal-expr.html
 [_SimplePath_]: paths.html#simple-paths
-[`allow`]: diagnostics.html#lint-check-attributes
+[`allow`]: attributes/diagnostics.html#lint-check-attributes
 [`cfg_attr`]: conditional-compilation.html#the-cfg_attr-attribute
 [`cfg`]: conditional-compilation.html#the-cfg-attribute
-[`cold`]: codegen.html#the-cold-attribute
+[`cold`]: attributes/codegen.html#the-cold-attribute
 [`crate_name`]: crates-and-source-files.html#the-crate_name-attribute
 [`crate_type`]: linkage.html
-[`deny`]: diagnostics.html#lint-check-attributes
-[`deprecated`]: diagnostics.html#the-deprecated-attribute
-[`derive`]: derive.html
+[`deny`]: attributes/diagnostics.html#lint-check-attributes
+[`deprecated`]: attributes/diagnostics.html#the-deprecated-attribute
+[`derive`]: attributes/derive.html
 [`export_name`]: abi.html#the-export_name-attribute
-[`forbid`]: diagnostics.html#lint-check-attributes
+[`forbid`]: attributes/diagnostics.html#lint-check-attributes
 [`global_allocator`]: runtime.html#the-global_allocator-attribute
-[`ignore`]: testing.html#the-ignore-attribute
-[`inline`]: codegen.html#the-inline-attribute
+[`ignore`]: attributes/testing.html#the-ignore-attribute
+[`inline`]: attributes/codegen.html#the-inline-attribute
 [`link_name`]: items/external-blocks.html#the-link_name-attribute
 [`link_section`]: abi.html#the-link_section-attribute
 [`link`]: items/external-blocks.html#the-link-attribute
 [`macro_export`]: macros-by-example.html#path-based-scope
 [`macro_use`]: macros-by-example.html#the-macro_use-attribute
 [`meta` macro fragment specifier]: macros-by-example.html
-[`must_use`]: diagnostics.html#the-must_use-attribute
-[`no_builtins`]: codegen.html#the-no_builtins-attribute
+[`must_use`]: attributes/diagnostics.html#the-must_use-attribute
+[`no_builtins`]: attributes/codegen.html#the-no_builtins-attribute
 [`no_implicit_prelude`]: items/modules.html#prelude-items
 [`no_link`]: items/extern-crates.html#the-no_link-attribute
 [`no_main`]: crates-and-source-files.html#the-no_main-attribute
@@ -279,16 +278,16 @@ The following is an index of all built-in attributes.
 [`proc_macro_attribute`]: procedural-macros.html#attribute-macros
 [`proc_macro_derive`]: procedural-macros.html#derive-macros
 [`proc_macro`]: procedural-macros.html#function-like-procedural-macros
-[`recursion_limit`]: compiler-attrs.html#the-recursion_limit-attribute
+[`recursion_limit`]: attributes/compiler-settings.html#the-recursion_limit-attribute
 [`repr`]: type-layout.html#representations
-[`should_panic`]: testing.html#the-should_panic-attribute
-[`test`]: testing.html#the-test-attribute
+[`should_panic`]: attributes/testing.html#the-should_panic-attribute
+[`test`]: attributes/testing.html#the-test-attribute
 [`used`]: abi.html#the-used-attribute
-[`warn`]: diagnostics.html#lint-check-attributes
+[`warn`]: attributes/diagnostics.html#lint-check-attributes
 [`windows_subsystem`]: runtime.html#the-windows_subsystem-attribute
 [attribute macros]: procedural-macros.html#attribute-macros
 [block expressions]: expressions/block-expr.html
-[built-in attributes]: #built-in-attributes
+[built-in attributes]: #built-in-attributes-index
 [derive macro helper attributes]: procedural-macros.html#derive-macro-helper-attributes
 [enum]: items/enumerations.html
 [expression statement]: statements.html#expression-statements

src/codegen.md → src/attributes/codegen.md

@@ -1,6 +1,6 @@
-# Code generation
+# Code generation attributes
 
-<!-- TODO: target_feature -->
+The following [attributes] are used for controlling code generation.
 
 ## Optimization hints
 
@@ -9,14 +9,10 @@ compile your code in a way that may be faster than what it would do without
 the hint. The attributes are only suggestions, and the compiler may choose to
 ignore it.
 
-Both attributes can be used on closures and [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.
-
-<!-- TODO: I believe it is currently not possible to use these on closures
-    because attributes are not allowed on expressions. May want to consider
-    removing "closure" here until it is stabilized. -->
+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
 
@@ -36,28 +32,15 @@ There are three ways to use the inline attribute:
 
 ### The `cold` attribute
 
-The *`cold` [attribute]* suggests to the compiler that the attributed function or
-closure is unlikely to be called.
-<!-- TODO: Expand this section.
-    Should the exact semantics be documented here, or in rustc book?
-    rustc:
-    - Reduces threshold for being inlined.
-    - "This calling convention attempts to make code in the caller as
-       efficient as possible under the assumption that the call is not commonly
-       executed.  As such, these calls often preserve all registers so that the
-       call does not break any live ranges in the caller side."
--->
+The *`cold` [attribute]* suggests to the compiler that the attributed function
+is unlikely to be called.
 
 ## The `no_builtins` attribute
 
 The *`no_builtins` [attribute]* may be applied at the crate level to disable
 optimizing certain code patterns to invocations of library functions that are
 assumed to exist.
 
-<!-- TODO: This needs more information.
-     This disables LTO, should that be mentioned, or in rustc book?
--->
-
 [attribute]: attributes.html
 [attributes]: attributes.html
 [functions]: items/functions.html

src/compiler-attrs.md → src/attributes/compiler-settings.md

@@ -1,9 +1,7 @@
-# Compiler attributes
+# Compiler setting attributes
 
 The following [attributes] affect internal settings of the compiler.
 
-<!-- TODO: feature -->
-
 ## The `recursion_limit` attribute
 
 The *`recursion_limit` attribute* may be applied at the crate level to set the
@@ -12,7 +10,5 @@ like auto-dereference or macro expansion. It uses the [_MetaNameValueStr_]
 syntax to specify the recursion depth. The default is
 `#![recursion_limit="64"]`.
 
-<!-- TODO: type_length_limit -->
-
 [attributes]: attributes.html
 [_MetaNameValueStr_]: attributes.html#meta-item-attribute-syntax

src/derive.md → src/attributes/derive.md

@@ -1,9 +1,5 @@
 # Derive
 
-<!-- TODO: Maybe link to https://doc.rust-lang.org/book/appendix-03-derivable-traits.html ?
-Should the reference say more about which traits are derivable?
--->
-
 The *`derive` attribute* allows certain traits to be automatically implemented
 for data structures. It uses the [_MetaListPaths_] syntax to specify a list of
 traits to implement.
@@ -37,7 +33,5 @@ impl<T: PartialEq> PartialEq for Foo<T> {
 
 You can implement `derive` for your own traits through [procedural macros].
 
-<!-- TODO: automatically_derived -->
-
 [_MetaListPaths_]: attributes.html#meta-item-attribute-syntax
 [procedural macros]: procedural-macros.html

src/diagnostics.md → src/attributes/diagnostics.md

@@ -1,4 +1,7 @@
-# Diagnostics
+# Diagnostic attributes
+
+The following [attributes] are used for controlling or generating diagnostic
+messages during compilation.
 
 ## Lint check attributes
 
@@ -250,6 +253,7 @@ message will be given alongside the warning.
 [_MetaListPaths_]: attributes.html#meta-item-attribute-syntax
 [_MetaNameValueStr_]: attributes.html#meta-item-attribute-syntax
 [`Drop`]: special-types-and-traits.html#drop
+[attributes]: attributes.html
 [block expression]: expressions/block-expr.html
 [call expression]: expressions/call-expr.html
 [enum variant]: items/enumerations.html

src/testing.md → src/attributes/testing.md

@@ -1,13 +1,17 @@
-# Testing
+# Testing attributes
+
+The following [attributes] are used for specifying functions for performing
+tests. Compiling a crate in "test" mode enables building the test functions
+along with a test harness for executing the tests. Enabling the test mode also
+enables the [`test` conditional compilation option].
 
 ## The `test` attribute
 
-The compiler comes with a default test framework. It works by attributing
-functions with the `test` attribute. These functions are only compiled when
-compiling with the test harness. Like [main], functions annotated with this
-attribute must take no arguments, must not declare any
-[trait or lifetime bounds], must not have any [where clauses], and its return
-type must be one of the following:
+The *`test` attribute* marks a function to be executed as a test when the
+crate is compiled in test mode. These functions are only compiled when
+compiling in test mode. Test functions must take no arguments, must not
+declare any [trait or lifetime bounds], must not have any [where clauses], and
+its return type must be one of the following:
 
 * `()`
 * `Result<(), E> where E: Error`
@@ -20,8 +24,8 @@ type must be one of the following:
 <!-- If the previous section needs updating (from "must take no arguments"
   onwards, also update it in the crates-and-source-files.md file -->
 
-> Note: The test harness is ran by passing the `--test` argument to `rustc` or
-> using `cargo test`.
+> Note: The test mode is enabled by passing the `--test` argument to `rustc`
+> or using `cargo test`.
 
 Tests that return `()` pass as long as they terminate and do not panic. Tests
 that return a `Result` pass as long as they return `Ok(())`. Tests that do not
@@ -83,6 +87,7 @@ fn mytest() {
 [_MetaListNameValueStr_]: attributes.html#meta-item-attribute-syntax
 [_MetaNameValueStr_]: attributes.html#meta-item-attribute-syntax
 [`Termination`]: ../std/process/trait.Termination.html
-[main]: crates-and-source-files.html
+[`test` conditional compilation option]: conditional-compilation.html#test
+[attributes]: attributes.html
 [trait or lifetime bounds]: trait-bounds.html
 [where clauses]: items/generics.html#where-clauses

src/conditional-compilation.md

@@ -297,7 +297,7 @@ println!("I'm running on a {} machine!", machine_kind);
 [IDENTIFIER]: identifiers.html
 [RAW_STRING_LITERAL]: tokens.html#raw-string-literals
 [STRING_LITERAL]: tokens.html#string-literals
-[Testing]: testing.html
+[Testing]: attributes/testing.html
 [_Attr_]: attributes.html
 [`--cfg`]: ../rustc/command-line-arguments.html#a--cfg-configure-the-compilation-environment
 [`--test`]: ../rustc/command-line-arguments.html#a--test-build-a-test-harness

src/crates-and-source-files.md

@@ -143,9 +143,6 @@ name of the crate with the [_MetaNameValueStr_] syntax.
 The crate name must not be empty, and must only contain [Unicode alphanumeric]
 or `-` (U+002D) characters.
 
-<!-- TODO: I feel like this should say more about what the crate name is and
-    what it is used for. -->
-
 [^phase-distinction]: This distinction would also exist in an interpreter.
     Static checks like syntactic analysis, type checking, and lints should
     happen before the program is executed regardless of when it is executed.

src/expressions/block-expr.md

@@ -148,7 +148,7 @@ fn is_unix_platform() -> bool {
 [statement]: statements.html
 [statements]: statements.html
 [struct]: expressions/struct-expr.html
-[the lint check attributes]: diagnostics.html#lint-check-attributes
+[the lint check attributes]: attributes/diagnostics.html#lint-check-attributes
 [tuple expressions]: expressions/tuple-expr.html
 [unsafe operations]: unsafety.html
 [value expressions]: expressions.html#place-expressions-and-value-expressions

src/expressions/match-expr.md

@@ -141,8 +141,8 @@ expressions].
 [_InnerAttribute_]: attributes.html
 [_OuterAttribute_]: attributes.html
 [`cfg`]: conditional-compilation.html
-[`cold`]: codegen.html#the-cold-attribute
-[lint check attributes]: diagnostics.html#lint-check-attributes
+[`cold`]: attributes/codegen.html#the-cold-attribute
+[lint check attributes]: attributes/diagnostics.html#lint-check-attributes
 [Range Expression]: expressions/range-expr.html
 
 [_Pattern_]: patterns.html

src/items/external-blocks.md

@@ -92,7 +92,7 @@ Finally, there are some rustc-specific ABI strings:
 * `extern "platform-intrinsic"` -- Specific platform intrinsics -- like, for
   example, `sqrt` -- have this ABI. You should never have to deal with it.
 
-## Variadic Functions
+## Variadic functions
 
 Functions within external blocks may be variadic by specifying `...` after one
 or more named arguments in the argument list:
@@ -121,8 +121,6 @@ the following possible values:
 - `framework` — Indicates a macOS framework. This is only valid for macOS
   targets.
 
-<!-- TODO: Document wasm_import_module, see https://github.com/rust-lang/rust/pull/52445 -->
-
 ```rust,ignore
 #[link(name = "crypto")]
 extern {