documenting AM

.github/workflows/gen-docs.yml

@@ -29,7 +29,7 @@ jobs:
         uses: actions-rs/cargo@v1
         with:
           command: doc
-          args: --features raylib/nobuild
+          args: --features raylib/nobuild -p game_logic --no-deps --document-private-items
       - name: Build mdBook
         run: mdbook build
 

.vscode/tasks.json

@@ -17,6 +17,20 @@
 				"$rustc"
 			],
 			"label": "Launch Game"
+		},
+		{
+			"type": "cargo",
+			"command": "doc",
+			"args": [
+				"-p",
+				"game_logic",
+				"--no-deps",
+				"--document-private-items"
+			],
+			"problemMatcher": [
+				"$rustc"
+			],
+			"label": "Regenerate RustDoc"
 		}
 	]
 }

game/game_logic/src/asset_manager/datastore.rs

@@ -1,4 +1,9 @@
-
+//! Access to the game's embedded files.
+//! 
+//! ## Overview
+//! 
+//! As described in the [`asset_manager`](../index.html) page, this file contains the actual access API for the game's embedded files.
+//! To see how to use this, check out the [`rust-embed`](https://github.com/pyros2097/rust-embed) README.
 /// This structure is dynamically packed with the contents of `dist` at compile time
 /// 
 /// This process allows us to only distribute a single binary, and have all the game assets stored in memory automatically.

game/game_logic/src/asset_manager/json.rs

@@ -1,3 +1,5 @@
+//! Utilities for loading JSON from the embedded filesystem.
+
 use serde::de::DeserializeOwned;
 
 use super::datastore::InternalData;
@@ -15,6 +17,13 @@ pub enum InternalJsonLoadError {
 }
 
 /// Load an embedded JSON file
+///
+/// **This is a blocking function call**
+/// 
+/// ## Errors
+///
+/// This may raise an error either because the requested asset was not found, or because the JSON data could not be deserialized.
+/// See [`InternalJsonLoadError`](enum.InternalJsonLoadError.html) for more information.
 pub fn load_json_structure<'a, T: DeserializeOwned>(
     dist_path: &str,
 ) -> Result<T, InternalJsonLoadError> {

game/game_logic/src/asset_manager/mod.rs

@@ -1,2 +1,23 @@
-pub mod datastore;
+//! Embedded asset management.
-pub mod json;
+//!
+//! ## Overview
+//!
+//! `asset_manager` is one of the most important modules in this project. It handles loading and packaging of in-game resources.
+//! Generally in a game, you might distribute an executable along with a zip of everything needed to run, 
+//! but we have had some issues with this before on systems with restrictive file permissions (cough OSX).
+//! 
+//! To make the game distribution process easier, we embed our resources directly into the executable's data section using 
+//! [`rust-embed`](https://github.com/pyros2097/rust-embed). This means we only have to distribute one single file to players.
+//! 
+//! ## Debug vs. Release mode
+//! 
+//! When the game is built in debug mode (with `cargo build`), the resources are *not* packaged into the game. 
+//! Instead, they are read from disk, allowing us to modify them while the game is running, and speeding up the compile times.
+//! 
+//! When the game is built in release mode (with `cargo build --release`), the resources are packaged into the game as described above.
+//! This means the game will load faster, but also use more RAM.
+
+mod datastore;
+pub use datastore::InternalData;
+mod json;
+pub use json::{InternalJsonLoadError, load_json_structure};

game/game_logic/src/lib.rs

@@ -1,7 +1,14 @@
 //! This file is the main entry point for the game logic.
+//!
+//! ## Overview
+//!
+//! The main function in this module is `entrypoint()`. This is called from `desktop_wrapper` to start the game.
+//!
+//! This module also includes all the other sub-modules of the game. If you are viewing this document from the web, click on the modules below to see more info.
+#![doc(issue_tracker_base_url = "https://github.com/Ewpratten/ludum-dare-50/issues/")]
 
 use crate::{
-    asset_manager::json::load_json_structure,
+    asset_manager::load_json_structure,
     discord::{DiscordRpcSignal, DiscordRpcThreadHandle},
     project_constants::ProjectConstants,
 };
@@ -11,11 +18,11 @@ extern crate approx; // For the macro `relative_eq!`
 #[macro_use]
 extern crate log; // For the `info!`, `warn!`, etc. macros
 
-pub mod asset_manager;
+pub(crate) mod asset_manager;
-pub mod discord;
+pub(crate) mod discord;
-pub mod persistent;
+pub(crate) mod persistent;
-pub mod project_constants;
+pub(crate) mod project_constants;
-pub mod rendering;
+pub(crate) mod rendering;
 
 /// This is the game logic entrypoint. Despite being async,
 /// this is expected to block the main thread for rendering and stuff.

game/game_logic/src/project_constants.rs

@@ -1,3 +1,16 @@
+//! The rust side of the `dist/project-constants.json` file
+//! 
+//! ## Overview
+//! 
+//! This file contains a structure defining all data we want to load from the project constants file.
+//! Feel free to add anything you'd like here, just make sure the relavant data is also written in the JSON file so the game doesn't crash.
+//! You can treat these as constants. I just prefer storing this kind of data in JSON rather than hard-coding it in the program.
+//! 
+//! ## How this is loaded
+//! 
+//! Somewhere in `lib.rs`, a call is made to load this through the `asset_manager`. 
+//! Its all already set up, so you shouldn't have to worry about the logistics.
+
 use serde::Deserialize;
 
 /// This structure is filled with the contents of `dist/project-constants.json` at runtime