Merge pull request #1040 from ehuss/scopes

Add "scopes" chapter.

src/expressions/block-expr.md

@@ -15,6 +15,7 @@
 A *block expression*, or *block*, is a control flow expression and anonymous namespace scope for items and variable declarations.
 As a control flow expression, a block sequentially executes its component non-item declaration statements and then its final optional expression.
 As an anonymous namespace scope, item declarations are only in scope inside the block itself and variables declared by `let` statements are in scope from the next statement until the end of the block.
+See the [scopes] chapter for more details.
 
 The syntax for a block is `{`, then any [inner attributes], then any number of [statements], then an optional expression, called the final operand, and finally a `}`.
 
@@ -243,6 +244,7 @@ fn is_unix_platform() -> bool {
 [inner attributes]: ../attributes.md
 [method]: ../items/associated-items.md#methods
 [mutable reference]: ../types/pointer.md#mutables-references-
+[scopes]: ../names/scopes.md
 [shared references]: ../types/pointer.md#shared-references-
 [statement]: ../statements.md
 [statements]: ../statements.md

src/items.md

@@ -53,15 +53,14 @@ There are several kinds of items:
 * [implementations]
 * [`extern` blocks]
 
-Some items form an implicit scope for the declaration of sub-items. In other
-words, within a function or module, declarations of items can (in many cases)
-be mixed with the statements, control blocks, and similar artifacts that
-otherwise compose the item body. The meaning of these scoped items is the same
-as if the item was declared outside the scope — it is still a static item
-— except that the item's *path name* within the module namespace is
-qualified by the name of the enclosing item, or is private to the enclosing
-item (in the case of functions). The grammar specifies the exact locations in
-which sub-item declarations may appear.
+Items may be declared in the [root of the crate], a [module][modules], or a [block expression].
+A subset of items, called [associated items], may be declared in [traits] and [implementations].
+A subset of items, called external items, may be declared in [`extern` blocks].
+
+Items may be defined in any order, with the exception of [`macro_rules`] which has its own scoping behavior.
+[Name resolution] of item names allows items to be defined before or after where the item is referred to in the module or block.
+
+See [item scopes] for information on the scoping rules of items.
 
 [_ConstantItem_]: items/constant-items.md
 [_Enumeration_]: items/enumerations.md
@@ -82,15 +81,23 @@ which sub-item declarations may appear.
 [_Visibility_]: visibility-and-privacy.md
 [`extern crate` declarations]: items/extern-crates.md
 [`extern` blocks]: items/external-blocks.md
+[`macro_rules`]: macros-by-example.md
 [`use` declarations]: items/use-declarations.md
+[associated items]: items/associated-items.md
+[block expression]: expressions/block-expr.md
 [constant items]: items/constant-items.md
 [enumeration definitions]: items/enumerations.md
 [function definitions]: items/functions.md
 [implementations]: items/implementations.md
+[item scopes]: names/scopes.md#item-scopes
 [modules]: items/modules.md
+[name resolution]: names/name-resolution.md
 [paths]: paths.md
+[root of the crate]: crates-and-source-files.md
+[statement]: statements.md
 [static items]: items/static-items.md
 [struct definitions]: items/structs.md
 [trait definitions]: items/traits.md
+[traits]: items/traits.md
 [type definitions]: items/type-aliases.md
 [union definitions]: items/unions.md

src/items/generics.md

@@ -23,6 +23,7 @@ parameters are listed in angle <span class="parenthetical">brackets (`<...>`)</s
 usually immediately after the name of the item and before its definition. For
 implementations, which don't have a name, they come directly after `impl`.
 The order of generic parameters is restricted to lifetime parameters and then type and const parameters intermixed.
+The same parameter name may not be declared more than once in a _GenericParams_ list.
 
 Some examples of items with type, const, and lifetime parameters:
 
@@ -37,6 +38,7 @@ struct EitherOrderWorks<const N: bool, U>(U);
 Generic parameters are in scope within the item definition where they are
 declared. They are not in scope for items declared within the body of a
 function as described in [item declarations].
+See [generic parameter scopes] for more details.
 
 [References], [raw pointers], [arrays], [slices], [tuples], and
 [function pointers] have lifetime or type parameters as well, but are not
@@ -286,6 +288,7 @@ struct Foo<#[my_flexible_clone(unbounded)] H> {
 [functions]: functions.md
 [function pointers]: ../types/function-pointer.md
 [generic implementations]: implementations.md#generic-implementations
+[generic parameter scopes]: ../names/scopes.md#generic-parameter-scopes
 [higher-ranked lifetimes]: ../trait-bounds.md#higher-ranked-trait-bounds
 [implementations]: implementations.md
 [item declarations]: ../statements.md#item-declarations

src/names.md

@@ -13,7 +13,7 @@ Some entities are [explicitly declared](#explicitly-declared-entities) in the
 source code, and some are [implicitly declared](#implicitly-declared-entities)
 as part of the language or compiler extensions.
 
-[*Paths*] are used to refer to an entity, possibly in another scope. Lifetimes
+[*Paths*] are used to refer to an entity, possibly in another module or type. Lifetimes
 and loop labels use a [dedicated syntax][lifetimes-and-loop-labels] using a
 leading quote.