apply feedback

src/unsafe-keyword.md

@@ -4,27 +4,25 @@ The `unsafe` keyword can occur in several different contexts:
 unsafe functions (`unsafe fn`), unsafe blocks (`unsafe {}`), unsafe traits (`unsafe trait`), and unsafe trait implementations (`unsafe impl`).
 It plays several different roles, depending on where it is used and whether the `unsafe_op_in_unsafe_fn` lint is enabled:
 - it is used to mark code that *defines* extra safety conditions (`unsafe fn`, `unsafe trait`)
-- it is used to mark code that needs to *satisfy* extra safety conditions (`unsafe {}`, `unsafe impl`, `unsafe fn` without `unsafe_op_in_unsafe_fn`)
+- it is used to mark code that needs to *satisfy* extra safety conditions (`unsafe {}`, `unsafe impl`, `unsafe fn` without [`unsafe_op_in_unsafe_fn`])
 
 The following discusses each of these cases.
 See the [keyword documentation][keyword] for some illustrative examples.
 
-[keyword]: ../std/keyword.unsafe.html
-
 ## Unsafe functions (`unsafe fn`)
 
 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 module defining an unsafe function is responsible for documenting what those extra safety conditions are.
+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.
 
-Such a function must be prefixed with the keyword `unsafe` and can only be called from inside an `unsafe` block.
+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 {}`)
 
 A block of code can be prefixed with the `unsafe` keyword, to permit calling `unsafe` functions or dereferencing raw pointers.
 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.
+this can be changed by enabling the [`unsafe_op_in_unsafe_fn`] lint.
 
 By putting operations into an unsafe block, the programmer states that they have taken care of satisfying the extra safety conditions of all operations inside that block.
 
@@ -39,11 +37,12 @@ For example, Rust provides the language features necessary to implement memory-s
 Rust's type system is a conservative approximation of the dynamic safety requirements, so in some cases there is a performance cost to using safe code.
 For example, a doubly-linked list is not a tree structure and can only be represented with reference-counted pointers in safe code.
 By using `unsafe` blocks to represent the reverse links as raw pointers, it can be implemented without reference counting.
+(See ["Learn Rust With Entirely Too Many Linked Lists"](https://rust-unofficial.github.io/too-many-lists/) for a more in-depth exploration of this particular example.)
 
 ## Unsafe traits (`unsafe trait`)
 
 An unsafe trait is a trait that comes with extra safety conditions that must be upheld by *implementations* of the trait.
-The module defining an unsafe trait is responsible for documenting what those extra safety conditions are.
+The unsafe trait should come with documentation explaining what those extra safety conditions are.
 
 Such a trait must be prefixed with the keyword `unsafe` and can only be implemented by `unsafe impl` blocks.
 
@@ -53,3 +52,7 @@ When implementing an unsafe trait, the implementation needs to be prefixed with
 By writing `unsafe impl`, the programmer states that they have taken care of satisfying the extra safety conditions required by the trait.
 
 Unsafe trait implementations are the logical dual to unsafe traits: where unsafe traits define a proof obligation that implementations must uphold, unsafe implementations state that all relevant proof obligations have been discharged.
+
+[keyword]: ../std/keyword.unsafe.html
+[`get_unchecked`]: ../std/primitive.slice.html#method.get_unchecked
+[`unsafe_op_in_unsafe_fn`]: ../rustc/lints/listing/allowed-by-default.html#unsafe-op-in-unsafe-fn