fix docs for new clippy lint.

There are a bunch of doccomments whose first lines are (much) too long.
Most of these are also difficult to understand and/or out-of-date. Just
rewrite them all.

secp256k1-sys/src/lib.rs

@@ -41,13 +41,14 @@ pub const SECP256K1_SER_UNCOMPRESSED: c_uint = (1 << 1);
 /// Flag for keys to indicate compressed serialization format
 pub const SECP256K1_SER_COMPRESSED: c_uint = (1 << 1) | (1 << 8);
 
-/// A nonce generation function. Ordinary users of the library
+/// A nonce generation function.
-/// never need to see this type; only if you need to control
+///
-/// nonce generation do you need to use it. I have deliberately
+/// Ordinary users of the library never need to see this type; the default
-/// made this hard to do: you have to write your own wrapper
+/// nonce generation function should be sufficient for almost all usecases.
-/// around the FFI functions to use it. And it's an unsafe type.
+///
-/// Nonces are generated deterministically by RFC6979 by
+/// To use this type, you must write your own (unsafe) wrapper. It is unsafe
-/// default; there should be no need to ever change this.
+/// because any secure implementation must dereference the passed-in raw
+/// pointers and/or call FFI functions.
 pub type NonceFn = Option<unsafe extern "C" fn(
     nonce32: *mut c_uchar,
     msg32: *const c_uchar,
@@ -66,11 +67,15 @@ pub type EcdhHashFn = Option<unsafe extern "C" fn(
     data: *mut c_void,
 ) -> c_int>;
 
-///  Same as secp256k1_nonce function with the exception of accepting an
+/// Same as [`NonceFn`], but accepts an additional pubkey argument and does not
-///  additional pubkey argument and not requiring an attempt argument. The pubkey
+/// accept an attempt argument.
-///  argument can protect signature schemes with key-prefixed challenge hash
+///
-///  inputs against reusing the nonce when signing with the wrong precomputed
+/// The pubkey argument will protect signature schemes with tweaked keys from
-///  pubkey.
+/// reusing the nonce when signing with a different precomputed pubkey, which
+/// for BIP 340 signatures is just as bad as reusing a nonce across different
+/// messages.
+///
+/// As with [`NonceFn`] ordinary users should never need to touch this type.
 pub type SchnorrNonceFn = Option<unsafe extern "C" fn(
     nonce32: *mut c_uchar,
     msg32: *const c_uchar,
@@ -119,10 +124,19 @@ impl SchnorrSigExtraParams {
     }
 }
 
-/// A Secp256k1 context, containing various precomputed values and such
+/// An opaque Secp256k1 context.
-/// needed to do elliptic curve computations. If you create one of these
+///
-/// with `secp256k1_context_create` you MUST destroy it with
+/// Currently this object contains a blinding factor used internally to
-/// `secp256k1_context_destroy`, or else you will have a memory leak.
+/// randomize computations to protect against sidechannel attacks. In the
+/// past it has contained precomputation tables to speed up crypto operations.
+///
+/// It should be assumed to be expensive to create and therefore should be
+/// reused when possible.
+///
+/// If you create one of these with `secp256k1_context_create` you must
+/// destroy it with `secp256k1_context_destroy`. (Failure to destroy it is
+/// a memory leak; destroying it using any other allocator is undefined
+/// behavior.)
 #[derive(Clone, Debug)]
 #[repr(C)] pub struct Context(c_int);
 

src/ellswift.rs

@@ -71,8 +71,9 @@ where
     1
 }
 
-/// `ElligatorSwift` is an encoding of a uniformly chosen point on the curve
+/// An encoding of an elliptic curvepoint such that a uniformly random on-curve
-/// as a 64-byte array that is indistinguishable from a uniformly random array.
+/// point will be encoded as uniformly random bits.
+///
 /// This object holds two field elements u and t, which are the inputs to
 /// the `ElligatorSwift` encoding function.
 #[derive(Copy, Clone, Debug, PartialEq, Eq, PartialOrd, Ord, Hash)]
@@ -280,10 +281,15 @@ impl ElligatorSwiftSharedSecret {
     pub const fn as_secret_bytes(&self) -> &[u8; 32] { &self.0 }
 }
 
-/// Represents which party we are in the ECDH, A is the initiator, B is the responder.
+/// Represents which party we are in the ECDH.
-/// This is important because the hash of the shared secret is different depending on which party
+///
-/// we are. In this context, "we" means the party that is using this library, and possesses the
+/// Here `A` is the initiator and `B` is the responder.
-/// secret key passed to `ElligatorSwift::shared_secret`.
+///
+/// this context, "we" means the party that possesses the secret key passed to
+/// [`ElligatorSwift::shared_secret`].
+///
+/// This distinction is important because the different parties compute different
+/// hashes of the shared secret.
 #[derive(Copy, Clone, Debug, PartialEq, Eq, PartialOrd, Ord, Hash)]
 pub enum ElligatorSwiftParty {
     /// We are the initiator of the ECDH

src/lib.rs

@@ -194,9 +194,13 @@ use crate::ffi::CPtr;
 pub use crate::key::{InvalidParityValue, Keypair, Parity, PublicKey, SecretKey, XOnlyPublicKey};
 pub use crate::scalar::Scalar;
 
-/// Trait describing something that promises to be a 32-byte random number; in particular,
+/// Trait describing something that promises to be a 32-byte uniformly random number.
-/// it has negligible probability of being zero or overflowing the group order. Such objects
+///
-/// may be converted to `Message`s without any error paths.
+/// In particular, anything implementing this trait must have neglibile probability
+/// of being zero, overflowing the group order, or equalling any specific value.
+///
+/// Since version 0.29 this has been deprecated; users should instead implement
+/// `Into<Message>` for types that satisfy these properties.
 #[deprecated(
     since = "0.29.0",
     note = "Please see v0.29.0 rust-secp256k1/CHANGELOG.md for suggestion"