Add docs

src/lib.rs

@@ -1,23 +1,62 @@
+//! Encode RSA's Public Key as a Magic Public Key
+//!
+//! This implementation has been reverse-engineered from Mastodon's implementation, since no
+//! documentation for the Magic Public Key format could be found online (Maybe I didn't look hard
+//! enough).
+//!
+//! ### Examples
+//! From private key
+//! ```rust
+//! # let mut rng = rand::thread_rng();
+//! # let private_key = rsa::RSAPrivateKey::new(&mut rng, 2048).unwrap();
+//! use rsa_magic_public_key::AsMagicPublicKey;
+//! let string = private_key.as_magic_public_key();
+//! ```
+//! From public key
+//! ```rust
+//! # let mut rng = rand::thread_rng();
+//! # let private_key = rsa::RSAPrivateKey::new(&mut rng, 2048).unwrap();
+//! # let public_key = private_key.to_public_key();
+//! use rsa_magic_public_key::AsMagicPublicKey;
+//! let string = public_key.as_magic_public_key();
+//! ```
+//! Parsing
+//! ```rust
+//! # use rsa_magic_public_key::AsMagicPublicKey;
+//! # let mut rng = rand::thread_rng();
+//! # let private_key = rsa::RSAPrivateKey::new(&mut rng, 2048).unwrap();
+//! # let magic_public_key = private_key.as_magic_public_key();
+//! use rsa::RSAPublicKey;
+//! use rsa_magic_public_key::FromMagicPublicKey;
+//! let public_key = RSAPublicKey::from_magic_public_key(&magic_public_key).unwrap();
+//! ```
 use base64::{decode_config, encode_config, URL_SAFE};
-use thiserror::Error;
 use num_bigint_dig::BigUint;
 use rsa::{PublicKey, RSAPublicKey};
+use thiserror::Error;
 
+/// Helper trait to add functionality to RSA types
 pub trait AsMagicPublicKey {
+    /// Produce a magic-public-key formatted string
     fn as_magic_public_key(&self) -> String;
 }
 
+/// Helper trait to add functionality to RSA types
 pub trait FromMagicPublicKey {
+    /// Parse a type from a magic-public-key formatted string
     fn from_magic_public_key(magic_public_key: &str) -> Result<Self, KeyError>
     where
         Self: Sized;
 }
 
 #[derive(Debug, Error)]
+/// Parsing errors
 pub enum KeyError {
+    /// The magic-public-key is not properly formatted
     #[error("The provided key is malformed")]
     Malformed,
 
+    /// The magic-public-key is not RSA
     #[error("The provided key is of the wrong kind")]
     Kind,
 }