Added documentation for function_item_references lint

Added documentation for `function_item_references` lint to the rustc book and
fixed comments in the lint checker itself.

compiler/rustc_session/src/lint/builtin.rs

@@ -2648,6 +2648,30 @@ declare_lint! {
 }
 
 declare_lint! {
+    /// The `function_item_references` lint detects function references that are
+    /// formatted with [`fmt::Pointer`] or transmuted.
+    ///
+    /// [`fmt::Pointer`]: https://doc.rust-lang.org/std/fmt/trait.Pointer.html
+    ///
+    /// ### Example
+    ///
+    /// ```rust
+    /// fn foo() { }
+    ///
+    /// fn main() {
+    ///     println!("{:p}", &foo);
+    /// }
+    /// ```
+    ///
+    /// {{produces}}
+    ///
+    /// ### Explanation
+    ///
+    /// Taking a reference to a function may be mistaken as a way to obtain a
+    /// pointer to that function. This can give unexpected results when
+    /// formatting the reference as a pointer or transmuting it. This lint is
+    /// issued when function references are formatted as pointers, passed as
+    /// arguments bound by [`fmt::Pointer`] or transmuted.
     pub FUNCTION_ITEM_REFERENCES,
     Warn,
     "suggest casting functions to pointers when attempting to take references",