Merge pull request RustCrypto#117 from RustCrypto/aead/doc-improvements

aead: documentation improvements + doc_cfg

aead/Cargo.toml

@@ -21,3 +21,4 @@ std = ["alloc"]
 
 [package.metadata.docs.rs]
 all-features = true
+rustdoc-args = ["--cfg", "docsrs"]

aead/README.md

@@ -1,6 +1,66 @@
-# Authenticated Encryption with Additional Data
+# RustCrypto: Authenticated Encryption with Additional Data
 
-This crate provides the rust trait equivilent of the AEAD API defined in
-RFC5116. As a result, it should provide nearly drop-in support for any
-compliant AEAD scheme, including AES-GCM, AES-CCM, ChaCha20-Poly1305,
-AES-CBC-HMAC, etc.
+[![crate][crate-image]][crate-link]
+[![Docs][docs-image]][docs-link]
+![Apache2/MIT licensed][license-image]
+![Rust Version][rustc-image]
+[![Build Status][build-image]][build-link]
+
+This crate provides an abstract interface for [AEAD] ciphers, which guarantee
+both confidentiality and integrity, even from a powerful attacker who is
+able to execute [chosen-ciphertext attacks]. The resulting security property,
+[ciphertext indistinguishability], is considered a basic requirement for
+modern cryptographic implementations.
+
+See [RustCrypto/AEADs] for cipher implementations which use this trait.
+
+[Documentation][docs-link]
+
+## Minimum Supported Rust Version
+
+Rust **1.41** or higher.
+
+Minimum supported Rust version can be changed in the future, but it will be
+done with a minor version bump.
+
+## SemVer Policy
+
+- All on-by-default features of this library are covered by SemVer
+- MSRV is considered exempt from SemVer as noted above
+- The off-by-default features `derive-preview` and `digest-preview` are
+  unstable "preview" features which are also considered exempt from SemVer.
+  Breaking changes to these features will, like MSRV, be done with a minor
+  version bump.
+
+## License
+
+All crates licensed under either of
+
+ * [Apache License, Version 2.0](http://www.apache.org/licenses/LICENSE-2.0)
+ * [MIT license](http://opensource.org/licenses/MIT)
+
+at your option.
+
+### Contribution
+
+Unless you explicitly state otherwise, any contribution intentionally submitted
+for inclusion in the work by you, as defined in the Apache-2.0 license, shall be
+dual licensed as above, without any additional terms or conditions.
+
+[//]: # (badges)
+
+[crate-image]: https://img.shields.io/crates/v/aead.svg
+[crate-link]: https://crates.io/crates/aead
+[docs-image]: https://docs.rs/aead/badge.svg
+[docs-link]: https://docs.rs/aead/
+[license-image]: https://img.shields.io/badge/license-Apache2.0/MIT-blue.svg
+[rustc-image]: https://img.shields.io/badge/rustc-1.41+-blue.svg
+[build-image]: https://travis-ci.org/RustCrypto/traits.svg?branch=master
+[build-link]: https://travis-ci.org/RustCrypto/traits
+
+[//]: # (general links)
+
+[AEAD]: https://en.wikipedia.org/wiki/Authenticated_encryption
+[chosen-ciphertext attacks]: https://en.wikipedia.org/wiki/Chosen-ciphertext_attack
+[ciphertext indistinguishability]: https://en.wikipedia.org/wiki/Ciphertext_indistinguishability
+[RustCrypto/AEADs]: https://github.com/RustCrypto/AEADs

aead/src/lib.rs

@@ -1,4 +1,4 @@
-//! Authenticated Encryption with Associated Data (AEAD) traits
+//! [Authenticated Encryption with Associated Data] (AEAD) traits
 //!
 //! This crate provides an abstract interface for AEAD ciphers, which guarantee
 //! both confidentiality and integrity, even from a powerful attacker who is
@@ -8,12 +8,16 @@
 //!
 //! See [RustCrypto/AEADs] for cipher implementations which use this trait.
 //!
+//! [Authenticated Encryption with Associated Data]: https://en.wikipedia.org/wiki/Authenticated_encryption
 //! [chosen-ciphertext attacks]: https://en.wikipedia.org/wiki/Chosen-ciphertext_attack
 //! [ciphertext indistinguishability]: https://en.wikipedia.org/wiki/Ciphertext_indistinguishability
 //! [RustCrypto/AEADs]: https://github.com/RustCrypto/AEADs
 
 #![no_std]
+#![cfg_attr(docsrs, feature(doc_cfg))]
 #![forbid(unsafe_code)]
+#![doc(html_logo_url = "https://raw.githubusercontent.com/RustCrypto/meta/master/logo_small.png")]
+#![warn(missing_docs, rust_2018_idioms)]
 
 #[cfg(feature = "alloc")]
 extern crate alloc;
@@ -30,11 +34,12 @@ use alloc::vec::Vec;
 use core::fmt;
 use generic_array::{typenum::Unsigned, ArrayLength, GenericArray};
 
+/// Error type
 #[derive(Clone, Copy, Debug, Eq, Hash, Ord, PartialEq, PartialOrd)]
 pub struct Error;
 
 impl fmt::Display for Error {
-    fn fmt(&self, f: &mut fmt::Formatter) -> fmt::Result {
+    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
         f.write_str("aead::Error")
     }
 }
@@ -107,6 +112,7 @@ pub trait Aead {
     /// use a postfix tag will need to override this to correctly assemble the
     /// ciphertext message.
     #[cfg(feature = "alloc")]
+    #[cfg_attr(docsrs, doc(cfg(feature = "alloc")))]
     fn encrypt<'msg, 'aad>(
         &self,
         nonce: &GenericArray<u8, Self::NonceSize>,
@@ -165,6 +171,7 @@ pub trait Aead {
     /// use a postfix tag will need to override this to correctly parse the
     /// ciphertext message.
     #[cfg(feature = "alloc")]
+    #[cfg_attr(docsrs, doc(cfg(feature = "alloc")))]
     fn decrypt<'msg, 'aad>(
         &self,
         nonce: &GenericArray<u8, Self::NonceSize>,
@@ -218,6 +225,7 @@ pub trait AeadMut {
     /// See notes on [`Aead::encrypt()`] about allowable message payloads and
     /// Associated Additional Data (AAD).
     #[cfg(feature = "alloc")]
+    #[cfg_attr(docsrs, doc(cfg(feature = "alloc")))]
     fn encrypt<'msg, 'aad>(
         &mut self,
         nonce: &GenericArray<u8, Self::NonceSize>,
@@ -264,6 +272,7 @@ pub trait AeadMut {
     /// See notes on [`Aead::encrypt()`] and [`Aead::decrypt()`] about allowable
     /// message payloads and Associated Additional Data (AAD).
     #[cfg(feature = "alloc")]
+    #[cfg_attr(docsrs, doc(cfg(feature = "alloc")))]
     fn decrypt<'msg, 'aad>(
         &mut self,
         nonce: &GenericArray<u8, Self::NonceSize>,

signature/README.md

@@ -16,7 +16,7 @@ in the [`rsa`][4] crate.
 
 ## Minimum Supported Rust Version
 
-All crates in this repository support Rust **1.36** or higher.
+Rust **1.41** or higher.
 
 Minimum supported Rust version can be changed in the future, but it will be
 done with a minor version bump.
@@ -52,7 +52,7 @@ dual licensed as above, without any additional terms or conditions.
 [docs-image]: https://docs.rs/signature/badge.svg
 [docs-link]: https://docs.rs/signature/
 [license-image]: https://img.shields.io/badge/license-Apache2.0/MIT-blue.svg
-[rustc-image]: https://img.shields.io/badge/rustc-1.36+-blue.svg
+[rustc-image]: https://img.shields.io/badge/rustc-1.41+-blue.svg
 [build-image]: https://travis-ci.org/RustCrypto/traits.svg?branch=master
 [build-link]: https://travis-ci.org/RustCrypto/traits