Merge rust-bitcoin/rust-secp256k1#512: Improve docs crate wide

ec47198a17 Remove ONE_KEY (Tobin C. Harding)
d546c16134 Remove cfg docs feature requirements (Tobin C. Harding)
5a7cedef00 doc: Fix preallocated memory grammar (Tobin C. Harding)

Pull request description:

  Read over and improve various parts of the crate documentation. Note this is an API breaking PR because it removes the public `ONE_KEY` type that we exposed when writing the docs for the `secret` module, exposing this type was, in my opinion, a mistake.

ACKs for top commit:
  apoelstra:
    ACK ec47198a17

Tree-SHA512: cf8573e58c9498093b0df3f240501d3ad0a9d65e07d2f7c3a9e4116bac6ba366d3d41ac695f4e79010597124512a43b32b4ecb02b08d81226c527d5f77a1a541

src/context.rs

@@ -76,19 +76,19 @@ pub trait Signing: Context {}
 /// Marker trait for indicating that an instance of `Secp256k1` can be used for verification.
 pub trait Verification: Context {}
 
-/// Represents the set of capabilities needed for signing with a user preallocated memory.
+/// Represents the set of capabilities needed for signing (preallocated memory).
 #[derive(Copy, Clone, Debug, PartialEq, Eq, PartialOrd, Ord, Hash)]
 pub struct SignOnlyPreallocated<'buf> {
     phantom: PhantomData<&'buf ()>,
 }
 
-/// Represents the set of capabilities needed for verification with a user preallocated memory.
+/// Represents the set of capabilities needed for verification (preallocated memory).
 #[derive(Copy, Clone, Debug, PartialEq, Eq, PartialOrd, Ord, Hash)]
 pub struct VerifyOnlyPreallocated<'buf> {
     phantom: PhantomData<&'buf ()>,
 }
 
-/// Represents the set of all capabilities with a user preallocated memory.
+/// Represents the set of all capabilities (preallocated memory).
 #[derive(Copy, Clone, Debug, PartialEq, Eq, PartialOrd, Ord, Hash)]
 pub struct AllPreallocated<'buf> {
     phantom: PhantomData<&'buf ()>,
@@ -121,17 +121,14 @@ mod alloc_only {
     const ALIGN_TO: usize = core::mem::align_of::<AlignedType>();
 
     /// Represents the set of capabilities needed for signing.
-    #[cfg_attr(docsrs, doc(cfg(any(feature = "std", feature = "alloc"))))]
     #[derive(Copy, Clone, Debug, PartialEq, Eq, PartialOrd, Ord, Hash)]
     pub enum SignOnly {}
 
     /// Represents the set of capabilities needed for verification.
-    #[cfg_attr(docsrs, doc(cfg(any(feature = "std", feature = "alloc"))))]
     #[derive(Copy, Clone, Debug, PartialEq, Eq, PartialOrd, Ord, Hash)]
     pub enum VerifyOnly {}
 
     /// Represents the set of all capabilities.
-    #[cfg_attr(docsrs, doc(cfg(any(feature = "std", feature = "alloc"))))]
     #[derive(Copy, Clone, Debug, PartialEq, Eq, PartialOrd, Ord, Hash)]
     pub enum All {}
 
@@ -301,7 +298,7 @@ unsafe impl<'buf> Context for AllPreallocated<'buf> {
 }
 
 impl<'buf, C: Context + 'buf> Secp256k1<C> {
-    /// Lets you create a context with preallocated buffer in a generic manner(sign/verify/all)
+    /// Lets you create a context with a preallocated buffer in a generic manner(sign/verify/all).
     pub fn preallocated_gen_new(buf: &'buf mut [AlignedType]) -> Result<Secp256k1<C>, Error> {
         #[cfg(target_arch = "wasm32")]
         ffi::types::sanity_checks_for_wasm();

src/key.rs

@@ -74,9 +74,6 @@ impl str::FromStr for SecretKey {
     }
 }
 
-/// The number 1 encoded as a secret key.
-pub const ONE_KEY: SecretKey = SecretKey(constants::ONE);
-
 /// A Secp256k1 public key, used for verification of signatures.
 ///
 /// # Serde support

src/secret.rs

@@ -118,7 +118,9 @@ impl SecretKey {
     ///
     /// ```
     /// # #[cfg(feature = "std")] {
-    /// let key = secp256k1::ONE_KEY;
+    /// # use std::str::FromStr;
+    /// use secp256k1::SecretKey;
+    /// let key = SecretKey::from_str("0000000000000000000000000000000000000000000000000000000000000001").unwrap();
     ///
     /// // Normal debug hides value (`Display` is not implemented for `SecretKey`).
     /// // E.g., `format!("{:?}", key)` prints "SecretKey(#2518682f7819fb2d)".
@@ -152,12 +154,11 @@ impl KeyPair {
     ///
     /// ```
     /// # #[cfg(feature = "std")] {
-    /// use secp256k1::ONE_KEY;
+    /// # use std::str::FromStr;
-    /// use secp256k1::KeyPair;
+    /// use secp256k1::{KeyPair, Secp256k1, SecretKey};
-    /// use secp256k1::Secp256k1;
     ///
     /// let secp = Secp256k1::new();
-    /// let key = ONE_KEY;
+    /// let key = SecretKey::from_str("0000000000000000000000000000000000000000000000000000000000000001").unwrap();
     /// let key = KeyPair::from_secret_key(&secp, &key);
     /// // Here we explicitly display the secret value:
     /// assert_eq!(
@@ -190,7 +191,7 @@ impl SharedSecret {
     /// # #[cfg(not(fuzzing))]
     /// # #[cfg(feature = "std")] {
     /// # use std::str::FromStr;
-    /// # use secp256k1::{SecretKey, PublicKey};
+    /// use secp256k1::{SecretKey, PublicKey};
     /// use secp256k1::ecdh::SharedSecret;
     ///
     /// # let pk = PublicKey::from_slice(&[3, 23, 183, 225, 206, 31, 159, 148, 195, 42, 67, 115, 146, 41, 248, 140, 11, 3, 51, 41, 111, 180, 110, 143, 114, 134, 88, 73, 198, 174, 52, 184, 78]).expect("hard coded slice should parse correctly");