feat(docs): document public api in game.rs and db.rs

.drone.yml

@@ -6,5 +6,6 @@ steps:
 - name: cargo test
   image: rust:latest
   commands:
+  - export DATABASE_URL=/tmp/save-sync.db
   - cargo build --all
   - cargo test --all

src/db.rs

@@ -3,6 +3,17 @@ use diesel::sqlite::SqliteConnection;
 use dotenv::dotenv;
 use std::env;
 
+/// Establishes a DB Connection with a Sqlite Database
+///
+/// Will **panic** if:
+/// * `$DATABASE_URL` is not set
+/// * Save Sync fails to connect to the database at `$DATABASE_URL`
+///
+/// # Examples
+/// ```
+/// # use save_sync::db::establish_connection;
+/// let connection = establish_connection();
+/// ```
 pub fn establish_connection() -> SqliteConnection {
     dotenv().ok();
 

src/game.rs

@@ -9,6 +9,7 @@ use uuid::Uuid;
 // TODO: Change this seed
 const XXHASH64_SEED: u64 = 1337;
 
+/// GameSaveLocation represents a path that holds the files of a Game's saves.
 #[derive(Debug, Clone)]
 pub struct GameSaveLocation {
     pub friendly_name: Option<String>,
@@ -18,6 +19,21 @@ pub struct GameSaveLocation {
 }
 
 impl GameSaveLocation {
+    /// Constructs a GameSaveLocation
+    ///
+    /// # Arguments
+    /// * `path` - The path of the Game Save(s)
+    /// * `files` - A Vector containing GameFiles, which are used to track the hashes of game files
+    /// * `friendly_name` - A Friendly name for the Game Save
+    ///
+    /// # Examples
+    /// ```
+    /// # use save_sync::game::{GameSaveLocation, GameFile};
+    /// let path = "/home/user/Documents/some_company/some_game/saves";
+    /// let files: Vec<GameFile> = Vec::new();
+    /// let friendly_name = "Some Game".to_string();
+    /// let game_save_location = GameSaveLocation::new(path, files, Some(friendly_name));
+    /// ```
     pub fn new<P>(path: P, files: Vec<GameFile>, friendly_name: Option<String>) -> Self
     where
         P: AsRef<Path>,
@@ -31,6 +47,10 @@ impl GameSaveLocation {
     }
 }
 
+/// GameFile is the representation of a on-disk file inside of a GameSaveLocation
+///
+/// This class keeps track of a Hash of the file, which allows Save Sync to identify when a
+/// tracked file has changed
 #[derive(Debug, Clone)]
 pub struct GameFile {
     pub original_path: PathBuf,
@@ -38,6 +58,23 @@ pub struct GameFile {
 }
 
 impl GameFile {
+    /// Constructs a new GameFile
+    ///
+    /// Will fail if:
+    ///  * Save Sync is unable to open and read the contents of the file at `path`
+    ///
+    /// # Arguments
+    /// * `path` - The path of the game file
+    ///
+    /// # Examples
+    /// ```
+    /// # use save_sync::game::GameFile;
+    /// let path = "/home/user/Documents/some_company/some_game/saves";
+    /// match GameFile::new(path) {
+    ///     Ok(_) => { /* Do something with the file  */ }
+    ///     Err(err) => { eprintln!("Error while attempting to calculate the hash of {}", path)}
+    /// };
+    /// ```
     pub fn new<P: AsRef<Path>>(path: P) -> std::io::Result<Self> {
         let path = path.as_ref();
         let file = File::open(path)?;
@@ -55,6 +92,7 @@ impl GameFile {
     }
 }
 
+/// The Error type for Interactions involving GameFiles
 #[derive(Error, Debug)]
 pub enum GameFileError {
     #[error(transparent)]
@@ -62,20 +100,18 @@ pub enum GameFileError {
 }
 
 #[derive(Debug, Default)]
-pub struct BackupPath {
+struct BackupPath {
     inner: Option<PathBuf>,
 }
 
 impl BackupPath {
-    pub fn new<P: AsRef<Path>>(path: P) -> Self {
+    fn new<P: AsRef<Path>>(path: P) -> Self {
         Self {
             inner: Some(path.as_ref().to_path_buf()),
         }
     }
 }
 
-impl BackupPath {}
-
 struct HashWriter<T: Hasher>(T);
 
 impl<T: Hasher> Write for HashWriter<T> {