Improve rustdocs for displaying secrets

Do minor improvements to the rustdocs to aid readability in the editor.

Author: tcharding

src/secret.rs

@@ -113,28 +113,26 @@ impl SecretKey {
     /// little-endian hexadecimal string using the provided formatter.
     ///
     /// This is the only method that outputs the actual secret key value, and, thus,
-    /// should be used with extreme precaution.
+    /// should be used with extreme caution.
     ///
-    /// # Example
+    /// # Examples
     ///
     /// ```
     /// # #[cfg(all(feature = "std", not(feature = "bitcoin_hashes")))] {
-    /// use secp256k1::ONE_KEY;
-    /// let key = ONE_KEY;
-    /// // Normal display hides value
-    /// assert_eq!(
-    ///     "SecretKey(#2518682f7819fb2d)",
-    ///     format!("{:?}", key)
-    /// );
+    /// let key = secp256k1::ONE_KEY;
+    ///
+    /// // Normal display hides value.
+    /// assert_eq!("SecretKey(#2518682f7819fb2d)", format!("{:?}", key));
+    ///
     /// // Here we explicitly display the secret value:
     /// assert_eq!(
     ///     "0000000000000000000000000000000000000000000000000000000000000001",
     ///     format!("{}", key.display_secret())
     /// );
+    /// // Also, we can explicitly display with `Debug`:
     /// assert_eq!(
-    ///     "DisplaySecret(\"0000000000000000000000000000000000000000000000000000000000000001\")",
-    ///     format!("{:?}", key.display_secret())
-    /// );
+    ///     format!("{:?}", key.display_secret()),
+    ///     format!("DisplaySecret(\"{}\")", key.display_secret()));
     /// # }
     /// ```
     #[inline]
@@ -172,6 +170,7 @@ impl KeyPair {
     ///     "0000000000000000000000000000000000000000000000000000000000000001",
     ///     format!("{}", key.display_secret())
     /// );
+    /// // Also, we can explicitly display with `Debug`:
     /// assert_eq!(
     ///     "DisplaySecret(\"0000000000000000000000000000000000000000000000000000000000000001\")",
     ///     format!("{:?}", key.display_secret())