Specify how names are introduced.

This is just a first pass to specifying how each thing introduces
a name, and where it is introduced. This is missing `use` and `Self`.
(And a few things I don't feel like need elaboration, like loop labels,
but those can be added if desired.)

Author: ehuss

src/items/constant-items.md

@@ -11,6 +11,8 @@ context when used. This includes usage of constants from external crates, and
 non-[`Copy`] types. References to the same constant are not necessarily
 guaranteed to refer to the same memory address.
 
+The constant declaration defines the constant value in the [value namespace] of the module or block where it is located.
+
 Constants must be explicitly typed. The type must have a `'static` lifetime: any
 references in the initializer must have `'static` lifetimes.
 
@@ -99,3 +101,4 @@ m!(const _: () = (););
 [_Type_]: ../types.md#type-expressions
 [_Expression_]: ../expressions.md
 [`Copy`]: ../special-types-and-traits.md#copy
+[value namespace]: ../names/namespaces.md

src/items/enumerations.md

@@ -30,6 +30,7 @@ nominal [enumerated type] as well as a set of *constructors*, that can be used
 to create or pattern-match values of the corresponding enumerated type.
 
 Enumerations are declared with the keyword `enum`.
+The `enum` declaration defines the enumeration type in the [type namespace] of the module or block where it is located.
 
 An example of an `enum` item and its use:
 
@@ -61,6 +62,27 @@ integer associated to it that is used to determine which variant it holds. An
 opaque reference to this discriminant can be obtained with the
 [`mem::discriminant`] function.
 
+Variant constructors are similar to [struct] definitions, and can be referenced by a path from the enumeration name, including in [use declarations].
+The constructors are defined in both the [type namespace] and [value namespace] within the enumeration.
+
+A struct-like variant can be instantiated with a [struct expression].
+A tuple-like variant can be instantiated with a [call expression].
+A unit-like variant can be instantiated with a [path expression].
+For example:
+
+```rust
+enum Examples {
+    UnitLike,
+    TupleLike(i32),
+    StructLike { value: i32 },
+}
+
+use Examples::*; // Creates aliases to all variants.
+let x = UnitLike; // Path expression of the const item.
+let y = TupleLike(123); // Call expression.
+let z = StructLike { value: 123 }; // Struct expression.
+```
+
 ## Custom Discriminant Values for Fieldless Enumerations
 
 If there is no data attached to *any* of the variants of an enumeration,
@@ -171,18 +193,25 @@ enum E {
 }
 ```
 
-[IDENTIFIER]: ../identifiers.md
-[_GenericParams_]: generics.md
-[_WhereClause_]: generics.md#where-clauses
 [_Expression_]: ../expressions.md
-[_TupleFields_]: structs.md
+[_GenericParams_]: generics.md
 [_StructFields_]: structs.md
+[_TupleFields_]: structs.md
 [_Visibility_]: ../visibility-and-privacy.md
-[enumerated type]: ../types/enum.md
+[_WhereClause_]: generics.md#where-clauses
+[`C` representation]: ../type-layout.md#the-c-representation
 [`mem::discriminant`]: ../../std/mem/fn.discriminant.html
-[never type]: ../types/never.md
-[numeric cast]: ../expressions/operator-expr.md#semantics
+[call expression]: ../expressions/call-expr.md
 [constant expression]: ../const_eval.md#constant-expressions
 [default representation]: ../type-layout.md#the-default-representation
+[enumerated type]: ../types/enum.md
+[IDENTIFIER]: ../identifiers.md
+[never type]: ../types/never.md
+[numeric cast]: ../expressions/operator-expr.md#semantics
+[path expression]: ../expressions/path-expr.md
 [primitive representation]: ../type-layout.md#primitive-representations
-[`C` representation]: ../type-layout.md#the-c-representation
+[struct expression]: ../expressions/struct-expr.md
+[struct]: structs.md
+[type namespace]: ../names/namespaces.md
+[use declarations]: use-declarations.md
+[value namespace]: ../names/namespaces.md

src/items/extern-crates.md

@@ -11,11 +11,9 @@
 >    `as` ( [IDENTIFIER] | `_` )
 
 An _`extern crate` declaration_ specifies a dependency on an external crate.
-The external crate is then bound into the declaring scope as the [identifier]
-provided in the `extern crate` declaration. Additionally, if the `extern
-crate` appears in the crate root, then the crate name is also added to the
-[extern prelude], making it automatically in scope in all modules. The `as`
-clause can be used to bind the imported crate to a different name.
+The external crate is then bound into the declaring scope as the given [identifier] in the [type namespace].
+Additionally, if the `extern crate` appears in the crate root, then the crate name is also added to the [extern prelude], making it automatically in scope in all modules.
+The `as` clause can be used to bind the imported crate to a different name.
 
 The external crate is resolved to a specific `soname` at compile time, and a
 runtime linkage requirement to that `soname` is passed to the linker for
@@ -78,6 +76,7 @@ crate to access only its macros.
 [`macro_use` attribute]: ../macros-by-example.md#the-macro_use-attribute
 [extern prelude]: ../names/preludes.md#extern-prelude
 [`macro_use` prelude]: ../names/preludes.md#macro_use-prelude
+[type namespace]: ../names/namespaces.md
 
 <script>
 (function() {

src/items/external-blocks.md

@@ -21,6 +21,8 @@ Two kind of item _declarations_ are allowed in external blocks: [functions] and
 [statics]. Calling functions or accessing statics that are declared in external
 blocks is only allowed in an `unsafe` context.
 
+The external block defines its functions and statics in the [value namespace] of the module or block where it is located.
+
 The `unsafe` keyword is syntactically allowed to appear before the `extern`
 keyword, but it is rejected at a semantic level. This allows macros to consume
 the syntax and make use of the `unsafe` keyword, before removing it from the
@@ -186,3 +188,4 @@ restrictions as [regular function parameters].
 [_Visibility_]: ../visibility-and-privacy.md
 [attributes]: ../attributes.md
 [regular function parameters]: functions.md#attributes-on-function-parameters
+[value namespace]: ../names/namespaces.md

src/items/functions.md

@@ -43,8 +43,9 @@
 >   in an associated function of a [trait item] in the 2015 edition.
 
 A _function_ consists of a [block], along with a name and a set of parameters.
-Other than a name, all these are optional. Functions are declared with the
-keyword `fn`. Functions may declare a set of *input* [*variables*][variables]
+Other than a name, all these are optional.
+Functions are declared with the keyword `fn` which defines the given name in the [value namespace] of the module or block where it is located.
+Functions may declare a set of *input* [*variables*][variables]
 as parameters, through which the caller passes arguments into the function, and
 the *output* [*type*][type] of the value the function will return to its caller
 on completion.
@@ -412,4 +413,5 @@ fn foo_oof(#[some_inert_attribute] arg: u8) {
 [method]: associated-items.md#methods
 [associated function]: associated-items.md#associated-functions-and-methods
 [implementation]: implementations.md
+[value namespace]: ../names/namespaces.md
 [variadic function]: external-blocks.md#variadic-functions

src/items/modules.md

@@ -34,11 +34,9 @@ mod math {
 }
 ```
 
-Modules and types share the same namespace. Declaring a named type with the
-same name as a module in scope is forbidden: that is, a type definition, trait,
-struct, enumeration, union, type parameter or crate can't shadow the name of a
-module in scope, or vice versa. Items brought into scope with `use` also have
-this restriction.
+Modules are defined in the [type namespace] of the module or block where it is located.
+It is an error to define multiple items with the same name in the same namespace within a module.
+See the [scopes chapter] for more details on restrictions and shadowing behavior.
 
 The `unsafe` keyword is syntactically allowed to appear before the `mod`
 keyword, but it is rejected at a semantic level. This allows macros to consume
@@ -149,7 +147,9 @@ The built-in attributes that have meaning on a module are [`cfg`],
 [attribute]: ../attributes.md
 [items]: ../items.md
 [module path]: ../paths.md
+[scopes chapter]: ../names/scopes.md
 [the lint check attributes]: ../attributes/diagnostics.md#lint-check-attributes
+[type namespace]: ../names/namespaces.md
 
 <script>
 (function() {

src/items/static-items.md

@@ -11,6 +11,8 @@ memory location. Static items have the `static` lifetime, which outlives all
 other lifetimes in a Rust program. Static items do not call [`drop`] at the
 end of the program.
 
+The static declaration defines the static value in the [value namespace] of the module or block where it is located.
+
 The static initializer is a [constant expression] evaluated at compile time.
 Static initializers may refer to other statics.
 
@@ -81,3 +83,4 @@ following are true:
 [IDENTIFIER]: ../identifiers.md
 [_Type_]: ../types.md#type-expressions
 [_Expression_]: ../expressions.md
+[value namespace]: ../names/namespaces.md

src/items/structs.md

@@ -37,6 +37,7 @@
 >    [_Type_]
 
 A _struct_ is a nominal [struct type] defined with the keyword `struct`.
+A struct declaration defines the given name in the [type namespace] of the module or block where it is located.
 
 An example of a `struct` item and its use:
 
@@ -46,11 +47,10 @@ let p = Point {x: 10, y: 11};
 let px: i32 = p.x;
 ```
 
-A _tuple struct_ is a nominal [tuple type], also defined with the keyword
-`struct`. For example:
-
-[struct type]: ../types/struct.md
-[tuple type]: ../types/tuple.md
+A _tuple struct_ is a nominal [tuple type], also defined with the keyword `struct`.
+In addition to defining a type, it also defines a constructor of the same name in the [value namespace].
+The constructor is a function which can be called to create a new instance of the struct.
+For example:
 
 ```rust
 struct Point(i32, i32);
@@ -59,7 +59,7 @@ let px: i32 = match p { Point(x, _) => x };
 ```
 
 A _unit-like struct_ is a struct without any fields, defined by leaving off the
-list of fields entirely. Such a struct implicitly defines a constant of its
+list of fields entirely. Such a struct implicitly defines a [constant] of its
 type with the same name. For example:
 
 ```rust
@@ -78,11 +78,15 @@ let c = [Cookie, Cookie {}, Cookie, Cookie {}];
 The precise memory layout of a struct is not specified. One can specify a
 particular layout using the [`repr` attribute].
 
-[`repr` attribute]: ../type-layout.md#representations
-
-[_OuterAttribute_]: ../attributes.md
-[IDENTIFIER]: ../identifiers.md
 [_GenericParams_]: generics.md
-[_WhereClause_]: generics.md#where-clauses
-[_Visibility_]: ../visibility-and-privacy.md
+[_OuterAttribute_]: ../attributes.md
 [_Type_]: ../types.md#type-expressions
+[_Visibility_]: ../visibility-and-privacy.md
+[_WhereClause_]: generics.md#where-clauses
+[`repr` attribute]: ../type-layout.md#representations
+[IDENTIFIER]: ../identifiers.md
+[constant]: constant-items.md
+[struct type]: ../types/struct.md
+[tuple type]: ../types/tuple.md
+[type namespace]: ../names/namespaces.md
+[value namespace]: ../names/namespaces.md

src/items/traits.md

@@ -17,6 +17,9 @@ interface consists of [associated items], which come in three varieties:
 - [types](associated-items.md#associated-types)
 - [constants](associated-items.md#associated-constants)
 
+The trait declaration defines the trait in the [type namespace] of the module or block where it is located.
+Associated items are defined as members of the trait within their respective namespaces: type namespace for associated types, and value namespace for constants and functions.
+
 All traits define an implicit type parameter `Self` that refers to "the type
 that is implementing this interface". Traits may also contain additional type
 parameters. These type parameters, including `Self`, may be constrained by
@@ -341,3 +344,4 @@ fn main() {
 [`Rc<Self>`]: ../special-types-and-traits.md#rct
 [`async`]: functions.md#async-functions
 [`const`]: functions.md#const-functions
+[type namespace]: ../names/namespaces.md

src/items/type-aliases.md

@@ -6,10 +6,9 @@
 >              ( `:` [_TypeParamBounds_] )<sup>?</sup>
 >              [_WhereClause_]<sup>?</sup> ( `=` [_Type_] )<sup>?</sup> `;`
 
-A _type alias_ defines a new name for an existing [type]. Type aliases are
-declared with the keyword `type`. Every value has a single, specific type, but
-may implement several different traits, or be compatible with several different
-type constraints.
+A _type alias_ defines a new name for an existing [type] in the [type namespace] of the module or block where it is located.
+Type aliases are declared with the keyword `type`.
+Every value has a single, specific type, but may implement several different traits, or be compatible with several different type constraints.
 
 For example, the following defines the type `Point` as a synonym for the type
 `(u8, u8)`, the type of pairs of unsigned 8 bit integers:
@@ -45,3 +44,4 @@ an [associated type] in a [trait].
 [associated type]: associated-items.md#associated-types
 [trait]: traits.md
 [type]: ../types.md
+[type namespace]: ../names/namespaces.md