Merge pull request #898 from ehuss/add-unsafe-mod-extern

Add `unsafe` for `mod` and `extern`.

Author: Havvy

Diff for: src/items/external-blocks.md

@@ -2,7 +2,7 @@
 
 > **<sup>Syntax</sup>**\
 > _ExternBlock_ :\
-> &nbsp;&nbsp; `extern` [_Abi_]<sup>?</sup> `{`\
+> &nbsp;&nbsp; `unsafe`<sup>?</sup> `extern` [_Abi_]<sup>?</sup> `{`\
 > &nbsp;&nbsp; &nbsp;&nbsp; [_InnerAttribute_]<sup>\*</sup>\
 > &nbsp;&nbsp; &nbsp;&nbsp; _ExternalItem_<sup>\*</sup>\
 > &nbsp;&nbsp; `}`
@@ -38,6 +38,11 @@ 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 `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
+token stream.
+
 ## Functions
 
 Functions within external blocks are declared in the same way as other Rust

Diff for: src/items/modules.md

@@ -2,8 +2,8 @@
 
 > **<sup>Syntax:</sup>**\
 > _Module_ :\
-> &nbsp;&nbsp; &nbsp;&nbsp; `mod` [IDENTIFIER] `;`\
-> &nbsp;&nbsp; | `mod` [IDENTIFIER] `{`\
+> &nbsp;&nbsp; &nbsp;&nbsp; `unsafe`<sup>?</sup> `mod` [IDENTIFIER] `;`\
+> &nbsp;&nbsp; | `unsafe`<sup>?</sup> `mod` [IDENTIFIER] `{`\
 > &nbsp;&nbsp; &nbsp;&nbsp;&nbsp;&nbsp; [_InnerAttribute_]<sup>\*</sup>\
 > &nbsp;&nbsp; &nbsp;&nbsp;&nbsp;&nbsp; [_Item_]<sup>\*</sup>\
 > &nbsp;&nbsp; &nbsp;&nbsp; `}`
@@ -40,6 +40,11 @@ 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.
 
+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
+the syntax and make use of the `unsafe` keyword, before removing it from the
+token stream.
+
 ## Module Source Filenames
 
 A module without a body is loaded from an external file. When the module does