elliptic-curve: include README.md in rustdoc + expand docs (#813)

Uses the new `doc = include_str!("...")` attribute to include README.md
in the rustdoc documentation.

Additionally fills out the toplevel rustdoc with a bit more information
about how the crate is intended to be used.

elliptic-curve/src/dev.rs

@@ -1,5 +1,7 @@
-//! Development-related functionality: helpers and types for writing tests
-//! against concrete implementations of the traits in this crate.
+//! Development-related functionality.
+//!
+//! Helpers and types for writing tests against concrete implementations of
+//! the traits in this crate.
 
 use crate::{
     bigint::{Limb, U256},

elliptic-curve/src/lib.rs

@@ -1,13 +1,32 @@
-//! General purpose Elliptic Curve Cryptography (ECC) support, including types
-//! and traits for representing various elliptic curve forms, scalars, points,
-//! and public/secret keys composed thereof.
+#![doc = include_str!("../README.md")]
+
+//! ## Usage
+//!
+//! This crate provides traits for describing elliptic curves, along with
+//! types which are generic over elliptic curves which can be used as the
+//! basis of curve-agnostic code.
+//!
+//! It's intended to be used with the following concrete elliptic curve
+//! implementations from the [`RustCrypto/elliptic-curves`] project:
 //!
-//! ## Minimum Supported Rust Version
+//! - [`bp256`]: brainpoolP256r1 and brainpoolP256t1
+//! - [`bp384`]: brainpoolP384r1 and brainpoolP384t1
+//! - [`k256`]: secp256k1 a.k.a. K-256
+//! - [`p256`]: NIST P-256 a.k.a secp256r1, prime256v1
+//! - [`p384`]: NIST P-384 a.k.a. secp384r1
 //!
-//! Rust **1.56** or higher.
+//! The [`ecdsa`] crate provides a generic implementation of the
+//! Elliptic Curve Digital Signature Algorithm which can be used with any of
+//! the above crates, either via an external ECDSA implementation, or
+//! using native curve arithmetic where applicable.
 //!
-//! Minimum supported Rust version can be changed in the future, but it will be
-//! done with a minor version bump.
+//! [`RustCrypto/elliptic-curves`]: https://github.com/RustCrypto/elliptic-curves
+//! [`bp256`]: https://github.com/RustCrypto/elliptic-curves/tree/master/bp256
+//! [`bp384`]: https://github.com/RustCrypto/elliptic-curves/tree/master/bp384
+//! [`k256`]: https://github.com/RustCrypto/elliptic-curves/tree/master/k256
+//! [`p256`]: https://github.com/RustCrypto/elliptic-curves/tree/master/p256
+//! [`p384`]: https://github.com/RustCrypto/elliptic-curves/tree/master/p384
+//! [`ecdsa`]: https://github.com/RustCrypto/signatures/tree/master/ecdsa
 
 #![no_std]
 #![cfg_attr(docsrs, feature(doc_cfg))]

elliptic-curve/src/secret_key.rs

@@ -53,7 +53,7 @@ use crate::{
 };
 
 #[cfg(all(docsrs, feature = "pkcs8"))]
-use {crate::pkcs8::FromPrivateKey, core::str::FromStr};
+use {crate::pkcs8::DecodePrivateKey, core::str::FromStr};
 
 /// Type label for PEM-encoded SEC1 private keys.
 #[cfg(feature = "pem")]
@@ -79,7 +79,7 @@ pub(crate) const SEC1_PEM_TYPE_LABEL: &str = "EC PRIVATE KEY";
 /// To decode an elliptic curve private key from PKCS#8, enable the `pkcs8`
 /// feature of this crate (or the `pkcs8` feature of a specific RustCrypto
 /// elliptic curve crate) and use the
-/// [`elliptic_curve::pkcs8::FromPrivateKey`][`FromPrivateKey`]
+/// [`elliptic_curve::pkcs8::DecodePrivateKey`][`DecodePrivateKey`]
 /// trait to parse it.
 ///
 /// When the `pem` feature of this crate (or a specific RustCrypto elliptic
@@ -188,7 +188,7 @@ where
     #[cfg(all(feature = "alloc", feature = "arithmetic", feature = "sec1"))]
     #[cfg_attr(
         docsrs,
-        doc(cfg(feature = "alloc", feature = "arithmetic", feature = "sec1"))
+        doc(cfg(all(feature = "alloc", feature = "arithmetic", feature = "sec1")))
     )]
     pub fn to_sec1_der(&self) -> der::Result<Zeroizing<Vec<u8>>>
     where