Document the derive macro sub-namespace

Author: jyn514

src/names/namespaces.md

@@ -110,9 +110,8 @@ r[names.namespaces.sub-namespaces]
 ## Sub-namespaces
 
 r[names.namespaces.sub-namespaces.intro]
-The macro namespace is split into two sub-namespaces: one for [bang-style macros] and one for [attributes].
-When an attribute is resolved, any bang-style macros in scope will be ignored.
-And conversely resolving a bang-style macro will ignore attribute macros in scope.
+The macro namespace is split into three sub-namespaces: [bang-style macros], [attributes], and [derives].
+When a macro from one sub-namespace is resolved, any macros from other sub-namespaces in scope will be ignored.
 This prevents one style from shadowing another.
 
 For example, the [`cfg` attribute] and the [`cfg` macro] are two different entities with the same name in the macro namespace, but they can still be used in their respective context.
@@ -136,6 +135,7 @@ It is still an error for a [`use` import] to shadow another macro, regardless of
 [Associated type declarations]: ../items/associated-items.md#associated-types
 [Attribute macros]: ../procedural-macros.md#attribute-macros
 [attributes]: ../attributes.md
+[derives]: ../attributes/derive.md
 [bang-style macros]: ../macros.md
 [Block labels]: ../expressions/loop-expr.md#labelled-block-expressions
 [boolean]: ../types/boolean.md

src/procedural-macros.md

@@ -94,7 +94,7 @@ These macros are defined by a [public] [function] with the `proc_macro`
 output [`TokenStream`] replaces the entire macro invocation.
 
 r[macro.proc.function.namespace]
-The `proc_macro` attribute defines the macro in the [macro namespace] in the root of the crate.
+The `proc_macro` attribute defines the macro in the [bang-style sub-namespace][sub-namespace] of the [macro namespace] in the root of the crate.
 
 For example, the following macro definition ignores its input and outputs a
 function `answer` into its scope.
@@ -144,7 +144,7 @@ Custom derive macros are defined by a [public] [function] with the
 `proc_macro_derive` attribute and a signature of `(TokenStream) -> TokenStream`.
 
 r[macro.proc.derive.namespace]
-The `proc_macro_derive` attribute defines the custom derive in the [macro namespace] in the root of the crate.
+The `proc_macro_derive` attribute defines the custom derive in the [derive sub-namespace][sub-namespace] of the [macro namespace] in the root of the crate.
 
 r[macro.proc.derive.output]
 The input [`TokenStream`] is the token stream of the item that has the `derive`
@@ -240,7 +240,7 @@ including other [attributes] on the [item]. The returned [`TokenStream`]
 replaces the [item] with an arbitrary number of [items].
 
 r[macro.proc.attribute.namespace]
-The `proc_macro_attribute` attribute defines the attribute in the [macro namespace] in the root of the crate.
+The `proc_macro_attribute` attribute defines the attribute in the [attribute sub-namespace][sub-namespace] of the [macro namespace] in the root of the crate.
 
 For example, this attribute macro takes the input stream and returns it as is,
 effectively being the no-op of attributes.
@@ -399,6 +399,7 @@ their equivalent `#[doc = r"str"]` attributes when passed to macros.
 [item]: items.md
 [items]: items.md
 [macro namespace]: names/namespaces.md
+[sub-namespace]: names/namespaces.md#sub-namespaces
 [module]: items/modules.md
 [patterns]: patterns.md
 [public]: visibility-and-privacy.md