Merge pull request #1619 from chorman0773/spec-add-identifiers-unsafety

Add spec identifier syntax to `unsafe-keyword.md` and `unsafety.md`

Author: traviscross

src/unsafe-keyword.md

@@ -1,5 +1,8 @@
 # The `unsafe` keyword
 
+r[unsafe]
+
+r[unsafe.intro]
 The `unsafe` keyword can occur in several different contexts:
 unsafe functions (`unsafe fn`), unsafe blocks (`unsafe {}`), unsafe traits (`unsafe trait`), unsafe trait implementations (`unsafe impl`), unsafe external blocks (`unsafe extern`), and unsafe attributes (`#[unsafe(attr)]`).
 It plays several different roles, depending on where it is used and whether the `unsafe_op_in_unsafe_fn` lint is enabled:
@@ -11,16 +14,25 @@ See the [keyword documentation][keyword] for some illustrative examples.
 
 ## Unsafe functions (`unsafe fn`)
 
+r[unsafe.fn]
+
+r[unsafe.fn.intro]
 Unsafe functions are functions that are not safe in all contexts and/or for all possible inputs.
 We say they have *extra safety conditions*, which are requirements that must be upheld by all callers and that the compiler does not check.
 For example, [`get_unchecked`] has the extra safety condition that the index must be in-bounds.
 The unsafe function should come with documentation explaining what those extra safety conditions are.
 
+r[unsafe.fn.safety]
 Such a function must be prefixed with the keyword `unsafe` and can only be called from inside an `unsafe` block, or inside `unsafe fn` without the [`unsafe_op_in_unsafe_fn`] lint.
 
 ## Unsafe blocks (`unsafe {}`)
 
+r[unsafe.block]
+
+r[unsafe.block.intro]
 A block of code can be prefixed with the `unsafe` keyword, to permit calling `unsafe` functions or dereferencing raw pointers.
+
+r[unsafe.block.fn-body]
 By default, the body of an unsafe function is also considered to be an unsafe block;
 this can be changed by enabling the [`unsafe_op_in_unsafe_fn`] lint.
 
@@ -41,13 +53,19 @@ By using `unsafe` blocks to represent the reverse links as raw pointers, it can
 
 ## Unsafe traits (`unsafe trait`)
 
+r[unsafe.trait]
+
+r[unsafe.trait.intro]
 An unsafe trait is a trait that comes with extra safety conditions that must be upheld by *implementations* of the trait.
 The unsafe trait should come with documentation explaining what those extra safety conditions are.
 
+r[unsafe.trait.safety]
 Such a trait must be prefixed with the keyword `unsafe` and can only be implemented by `unsafe impl` blocks.
 
 ## Unsafe trait implementations (`unsafe impl`)
 
+r[unsafe.impl]
+
 When implementing an unsafe trait, the implementation needs to be prefixed with the `unsafe` keyword.
 By writing `unsafe impl`, the programmer states that they have taken care of satisfying the extra safety conditions required by the trait.
 
@@ -59,12 +77,16 @@ Unsafe trait implementations are the logical dual to unsafe traits: where unsafe
 
 ## Unsafe external blocks (`unsafe extern`)
 
+r[unsafe.extern]
+
 The programmer who declares an [external block] must assure that the signatures of the items contained within are correct. Failing to do so may lead to undefined behavior.  That this obligation has been met is indicated by writing `unsafe extern`.
 
 [external block]: items/external-blocks.md
 
 ## Unsafe attributes (`#[unsafe(attr)]`)
 
+r[unsafe.attribute]
+
 An [unsafe attribute] is one that has extra safety conditions that must be upheld when using the attribute. The compiler cannot check whether these conditions have been upheld.  To assert that they have been, these attributes must be wrapped in `unsafe(..)`, e.g. `#[unsafe(no_mangle)]`.
 
 [unsafe attribute]: attributes.md

src/unsafety.md

@@ -1,17 +1,34 @@
 # Unsafety
 
+r[safety]
+
+r[safety.intro]
 Unsafe operations are those that can potentially violate the memory-safety
 guarantees of Rust's static semantics.
 
+r[safety.unsafe-ops]
 The following language level features cannot be used in the safe subset of
 Rust:
 
+r[safety.unsafe-deref]
 - Dereferencing a [raw pointer].
+
+r[safety.unsafe-static]
 - Reading or writing a [mutable] or [external] static variable.
+
+r[safety.unsafe-union-access]
 - Accessing a field of a [`union`], other than to assign to it.
+
+r[safety.unsafe-call]
 - Calling an unsafe function (including an intrinsic or foreign function).
+
+r[safety.unsafe-impl]
 - Implementing an [unsafe trait].
+
+r[safety.unsafe-extern]
 - Declaring an [`extern`] block.
+
+r[safety.unsafe-attribute]
 - Applying an [unsafe attribute] to an item.
 
 [`extern`]: items/external-blocks.md