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

Author: ehuss

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 renamed to 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 renamed to 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 renamed to 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 renamed to 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 renamed to 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.