document up the config logic

Signed-off-by: Christine Dodrill <me@christine.website>

crates/logtail-poster/src/config.rs

@@ -1,11 +1,6 @@
 use serde::{Deserialize, Serialize};
 use std::{env, ffi::OsString, fs, io, path::PathBuf};
 
-#[cfg(feature = "log-facade")]
-mod log;
-#[cfg(feature = "log-facade")]
-pub use self::log::*;
-
 pub(crate) fn cache_dir() -> Option<OsString> {
     let dir = env::var_os("STATE_DIRECTORY").or_else(|| {
         env::var_os("HOME").and_then(|dir| {
@@ -24,13 +19,18 @@ pub(crate) fn state_file(name: &str) -> Option<PathBuf> {
     Some(dir)
 }
 
+/// The logtail configuration file. This contains cached copies of public and private
+/// IDs, however in practice the most read value is the private ID.
 #[derive(Serialize, Deserialize, Eq, PartialEq, Debug)]
 pub struct Config {
+    // TODO(Xe): make this use a custom serde format, see https://serde.rs/custom-date-format.html
     private_id: String,
     public_id: String,
 }
 
 impl Config {
+    /// Constructs a brand new configuration, including a rng'd private ID and its public
+    /// counterpart.
     pub fn new() -> Self {
         let private_id = logtail::PrivateID::new();
 
@@ -40,10 +40,13 @@ impl Config {
         }
     }
 
+    /// Returns the logtail private ID for this Config.
     pub fn private_id(self) -> logtail::PrivateID {
         logtail::PrivateID::from_hex(self.private_id).unwrap()
     }
 
+    /// Loads the relevant configuration file off disk, and creates a new one if it
+    /// doesn't already exist. This function is idempotent.
     pub fn load<S>(collection: S) -> io::Result<Self>
     where
         S: Into<String>,

crates/logtail/src/lib.rs

@@ -36,6 +36,7 @@ impl PrivateID {
         hex::encode(self.0)
     }
 
+    /// Converts this private ID into its public equivalent.
     pub fn as_public(&self) -> PublicID {
         let mut hasher = Sha256::new();
         hasher.update(&self.0);