k256: ECDSA usage with initial end-to-end doctest (#105)

Adds an initial description of the crate's ECDSA-related cargo features
(`ecdsa-core` and `ecdsa`) along with a basic signing/verification usage
example.

k256/src/ecdsa.rs

@@ -1,7 +1,51 @@
-//! Elliptic Curve Digital Signature Algorithm (ECDSA)
+//! Elliptic Curve Digital Signature Algorithm (ECDSA).
+//!
+//! This module contains support for computing and verifying ECDSA signatures.
+//! To use it, you will need to enable one of the two following Cargo features:
+//!
+//! - `ecdsa-core`: provides only the [`Signature`] type (which represents an
+//!   ECDSA/secp256k1 signature). Does not require the `arithmetic` feature.
+//!   This is useful for 3rd-party crates which wish to use the `Signature`
+//!   type for interoperability purposes (particularly in conjunction with the
+//!   [`signature::Signer`] trait. Example use cases for this include other
+//!   software implementations of ECDSA/secp256k1 and wrappers for cloud KMS
+//!   services or hardware devices (HSM or crypto hardware wallet).
+//! - `ecdsa`: provides the [`Signature`], [`Signer`], and [`Verifier`] types
+//!   which natively implement ECDSA/secp256k1 signing and verification.
+//!
+//! ## Signing/Verification Example
+//!
+//! This example requires the `ecdsa` Cargo feature is enabled:
+//!
+//! ```
+//! # #[cfg(feature = "ecdsa")]
+//! # {
+//! use k256::{
+//!     ecdsa::{Signer, signature::RandomizedSigner},
+//!     elliptic_curve::{Generate, rand_core::OsRng},
+//!     SecretKey,
+//! };
+//!
+//! // Signing
+//! let secret_key = SecretKey::generate(&mut OsRng);
+//! let signer = Signer::new(&secret_key).expect("secret key invalid");
+//! let message = b"ECDSA proves knowledge of a secret number in the context of a single message";
+//! let signature = signer.sign_with_rng(&mut OsRng, message);
+//!
+//! // Verification
+//! use k256::{PublicKey, ecdsa::{Verifier, signature::Verifier as _}};
+//!
+//! let public_key = PublicKey::from_secret_key(&secret_key, true).expect("secret key invalid");
+//! let verifier = Verifier::new(&public_key).expect("public key invalid");
+//!
+//! assert!(verifier.verify(message, &signature).is_ok());
+//! # }
+//! ```
 
 pub mod recoverable;
 
+pub use ecdsa_core::signature;
+
 use super::Secp256k1;
 use core::borrow::Borrow;