age-core: Improve crate documentation

age-core/Cargo.toml

@@ -8,6 +8,10 @@ readme = "README.md"
 license = "MIT OR Apache-2.0"
 edition = "2018"
 
+[package.metadata.docs.rs]
+all-features = true
+rustdoc-args = ["--cfg", "docsrs"]
+
 [badges]
 maintenance = { status = "experimental" }
 

age-core/src/format.rs

@@ -1,3 +1,5 @@
+//! Core types and encoding operations used by the age file format.
+
 use rand::{
     distributions::{Distribution, Uniform},
     thread_rng, RngCore,
@@ -126,6 +128,7 @@ pub fn grease_the_joint() -> Stanza {
     Stanza { tag, args, body }
 }
 
+/// Decoding operations for age types.
 pub mod read {
     use nom::{
         branch::alt,
@@ -148,6 +151,8 @@ pub mod read {
         )
     }
 
+    /// Reads an age "arbitrary string".
+    ///
     /// From the age specification:
     /// ```text
     /// ... an arbitrary string is a sequence of ASCII characters with values 33 to 126.
@@ -273,6 +278,7 @@ pub mod read {
     }
 }
 
+/// Encoding operations for age types.
 pub mod write {
     use cookie_factory::{
         combinator::string,

age-core/src/lib.rs

@@ -1,3 +1,10 @@
+//! This crate contains common structs and functions used across the `age` crates.
+//!
+//! You are probably looking for the [`age`](https://crates.io/crates/age) crate
+//! itself. You should only need to directly depend on this crate if you are
+//! implementing a custom recipient type.
+
+#![cfg_attr(docsrs, feature(doc_cfg))]
 // Catch documentation errors caused by code changes.
 #![deny(broken_intra_doc_links)]
 
@@ -8,4 +15,5 @@ pub mod format;
 pub mod primitives;
 
 #[cfg(feature = "plugin")]
+#[cfg_attr(docsrs, doc(cfg(feature = "plugin")))]
 pub mod plugin;

age-core/src/plugin.rs

@@ -1,3 +1,8 @@
+//! Common structs and constants for the age plugin system.
+//!
+//! These are shared between the client implementation in the `age` crate, and the plugin
+//! implementations built around the `age-plugin` crate.
+
 use rand::{thread_rng, Rng};
 use secrecy::Zeroize;
 use std::fmt;