aes-gcm: improve doc example (#493)

Author: newpavlov

aes-gcm/src/lib.rs

@@ -12,15 +12,33 @@
 //!
 //! Simple usage (allocating, no associated data):
 //!
-#![cfg_attr(all(feature = "getrandom", feature = "std"), doc = "```")]
-#![cfg_attr(not(all(feature = "getrandom", feature = "std")), doc = "```ignore")]
-//! # fn main() -> Result<(), Box<dyn std::error::Error>> {
+//! ```
 //! use aes_gcm::{
 //!     aead::{Aead, AeadCore, KeyInit, OsRng},
-//!     Aes256Gcm, Nonce // Or `Aes128Gcm`
+//!     Aes256Gcm, Nonce, Key // Or `Aes128Gcm`
 //! };
 //!
-//! let key = Aes256Gcm::generate_key(&mut OsRng);
+//! # fn gen_key() -> Result<(), core::array::TryFromSliceError> {
+//! // The encryption key can be generated randomly:
+//! # #[cfg(all(feature = "getrandom", feature = "std"))] {
+//! let key = Aes256Gcm::generate_key(OsRng);
+//! # }
+//!
+//! // Transformed from a byte array:
+//! let key: &[u8; 32] = &[42; 32];
+//! let key: &Key<Aes256Gcm> = key.into();
+//!
+//! // Note that you can get byte array from slice using the `TryInto` trait:
+//! let key: &[u8] = &[42; 32];
+//! let key: [u8; 32] = key.try_into()?;
+//! # Ok(()) }
+//!
+//! # fn main() -> Result<(), aes_gcm::Error> {
+//! // Alternatively, the key can be transformed directly from a byte slice
+//! // (panicks on lenght mismatch):
+//! # let key: &[u8] = &[42; 32];
+//! let key = Key::<Aes256Gcm>::from_slice(key);
+//!
 //! let cipher = Aes256Gcm::new(&key);
 //! let nonce = Aes256Gcm::generate_nonce(&mut OsRng); // 96-bits; unique per message
 //! let ciphertext = cipher.encrypt(&nonce, b"plaintext message".as_ref())?;