Add documentation.

knox/src/prelude/attribute.rs

@@ -1,12 +1,22 @@
 use crate::pb::*;
 
+/// An `Attribute`'s different kinds of value.
+///
+/// An attribute's value can be stored in differnet form. This enum abstracts
+/// over those different types to provide a unique interface to the values.
 #[derive(Debug, PartialEq)]
 pub enum AttributeValue {
+  /// The typical representation of a standard attribute, a simple UTF-8 string
   String(String),
+  /// A binary presentation of a value, used for file contents.
   Binary(Vec<u8>),
 }
 
 impl Attribute {
+  /// Retrieve an `Attribute`'s value.
+  ///
+  /// Extracts a value from an attribute, and return an enum that allows to
+  /// abstract over the actuel storage representation.
   pub fn value(&self) -> AttributeValue {
     if self.file {
       match String::from_utf8(self.bytes_value.clone()) {

knox/src/prelude/entry.rs

@@ -10,6 +10,14 @@ use crate::pb::*;
 use crate::util;
 
 impl Entry {
+  /// Retrieves an entry.
+  ///
+  /// This function returns a decrypted `Entry` from its virtual path.
+  ///
+  /// # Arguments
+  ///
+  ///  * **path:** a virtual path to an `Entry`. This will be expanded to the
+  ///    real filesystem file backing the `Entry`.
   pub fn read<P>(handle: &VaultContext, path: P) -> Result<Entry, Box<dyn Error>>
   where
     P: AsRef<Path>,
@@ -20,6 +28,7 @@ impl Entry {
     Ok(message)
   }
 
+  /// Adds a standard string attribute to an Entry.
   pub fn add_attribute(&mut self, key: &str, value: &str) {
     let attribute = Attribute {
       value: value.to_string(),
@@ -29,6 +38,10 @@ impl Entry {
     self.attributes.insert(key.to_string(), attribute);
   }
 
+  /// Adds a confidential string attribute to an `Entry`.
+  ///
+  /// A confidential attribute is just represented by a boolean value and will
+  /// prevent automatic priting of the value to the console.
   pub fn add_confidential_attribute(&mut self, key: &str, value: &str) {
     let attribute = Attribute {
       value: value.to_string(),
@@ -39,6 +52,11 @@ impl Entry {
     self.attributes.insert(key.to_string(), attribute);
   }
 
+  /// Adds a file attribute to an `Entry`.
+  ///
+  /// A file attribute can contain the raw content of a filesystem file (string
+  /// or binary) and therefore will be encoded differently that string
+  /// attributes.
   pub fn add_file_attribute(&mut self, key: &str, value: &[u8]) {
     let mut attribute = Attribute {
       file: true,

knox/src/prelude/vault.rs

@@ -16,6 +16,16 @@ pub struct VaultContext {
 }
 
 impl VaultContext {
+  /// Create a new `Vault`.
+  ///
+  /// Initializes a new empty vault, encrypted with the provided GPG
+  /// identities.
+  ///
+  /// # Arguments
+  ///
+  ///  * `path`       - the filesystem path at which to create the vault.
+  ///  * `identities` - a slice if GPG identities, represented by their owner's
+  ///                   email address.
   pub fn create<P>(path: P, identities: &[String]) -> Result<Self, Box<dyn Error>>
   where
     P: AsRef<Path>,
@@ -52,6 +62,14 @@ impl VaultContext {
     })
   }
 
+  /// Return a handle to a `Vault` from the filesystem.
+  ///
+  /// Opens, decrypt the metadata of, and returns a handle that allows you to
+  /// manipulate a `Vault`.
+  ///
+  /// # Arguments
+  ///
+  ///  * `path` - filesystem path where the vault is located.
   pub fn open<P>(path: P) -> Result<Self, Box<dyn Error>>
   where
     P: AsRef<Path>,
@@ -73,6 +91,13 @@ impl VaultContext {
     })
   }
 
+  /// Write the vault metadata.
+  ///
+  /// Persists all changes to the vault's metadata into the `_knox.meta` file
+  /// containing the encrypted mapping between virtual (user) secret paths and
+  /// filesystem paths.
+  ///
+  /// This mapping collection is called the index..
   pub fn write(&self) -> Result<(), Box<dyn Error>> {
     create_dir_all(util::normalize_path(self, &""))?;
 
@@ -86,17 +111,43 @@ impl VaultContext {
     Ok(())
   }
 
+  /// Add an entry to the index.
+  ///
+  /// Adds an entry to the index of a vault, allowing to retrieve a filesystem
+  /// path from a virtual path. This does not manage the secret itself.
+  ///
+  /// # Arguments
+  ///
+  ///  * `path`        - virtual path to the entry.
+  ///  * `destination` - physical filesystem path to the entry.
   pub fn add_index(&mut self, path: &str, destination: &str) {
     self
       .vault
       .mut_index()
       .insert(path.to_string(), destination.to_string());
   }
 
+  /// Remove an entry from the index.
+  ///
+  /// Removes an entry to the index of a vault, allowing to retrieve a
+  /// filesystem path from a virtual path. This does not manage the secret
+  /// itself.
+  ///
+  /// # Arguments
+  ///
+  ///  * `path` - virtual path to the entry
   pub fn remove_index(&mut self, path: &str) {
     self.vault.mut_index().remove(path);
   }
 
+  /// Read an `Entry`.
+  ///
+  /// Takes a virtual path and returns the decrypted `Entry` from the vault, if
+  /// it exists.
+  ///
+  /// # Arguments
+  ///
+  ///  * `path` - the virtual path to the entry.
   pub fn read_entry(&self, path: &str) -> Result<Entry, Box<dyn Error>> {
     if !self.vault.get_index().contains_key(path) {
       return Err(VaultError::throw("no entry was found at this path"));
@@ -108,6 +159,15 @@ impl VaultContext {
     Ok(entry)
   }
 
+  /// Persist an `Entry`.
+  ///
+  /// Encrypts and writes an `Entry` to its physical location as described in
+  /// the vault's index. The entry must exist in the index beforehand.
+  ///
+  /// # Arguments
+  ///
+  ///  * `path`  - the virtual path to the entry.
+  ///  * `entry` - the `Entry` to be written.
   pub fn write_entry(&mut self, path: &str, entry: &Entry) -> Result<(), Box<dyn Error>> {
     let hash = util::hash_path(self.vault.get_index().get(path));
 
@@ -127,6 +187,14 @@ impl VaultContext {
     Ok(())
   }
 
+  /// Delete an `Entry`.
+  ///
+  /// Deletes an entry both from its backing filesystem location and from the
+  /// index.
+  ///
+  /// # Arguments
+  ///
+  ///  * `path` - the virtual path to the entry.
   pub fn delete_entry(&mut self, path: &str) -> Result<(), Box<dyn Error>> {
     if let Some(salt) = self.vault.get_index().get(path) {
       let hash = util::hash_path(Some(salt));
@@ -151,17 +219,40 @@ impl VaultContext {
     ))
   }
 
+  /// Check if a file exists under the vault's directory.
+  ///
+  /// # Arguments
+  ///
+  ///  * - `path` - a path relative to the vault's root directory.
   pub fn has_pack<P>(&self, path: P) -> bool
   where
     P: AsRef<Path>,
   {
     Path::new(&util::normalize_path(self, &path)).exists()
   }
 
+  /// Add an identity to the vault
+  ///
+  /// Saves a new identity to the vault's metadata. This does not touch any
+  /// existing secrets, which should be re-encrypted for the new identity to
+  /// be used.
+  ///
+  /// # Arguments
+  ///
+  ///  * `identity` - the GPG identity
   pub fn add_identity(&mut self, identity: &str) {
     self.vault.mut_identities().push(identity.to_string());
   }
 
+  /// Remove an identity from the vault.
+  ///
+  /// Removes an existing identity from the vault's metadata. This does not
+  /// touch any existing secrets, which should be re-encrypted for the
+  /// removed identity to be unable de decrypt them.
+  ///
+  /// # Arguments
+  ///
+  ///  * `identity` - the GPG identity
   pub fn remove_identity(&mut self, identity: &str) {
     let identities = self
       .vault