Documentation

crates/content/src/engine.rs

@@ -17,10 +17,18 @@ pub(super) mod syntax {
 	}
 }
 
+/// Represents an (foward) engine outfit that may be attached to a ship.
 #[derive(Debug, Clone)]
 pub struct Engine {
+	/// The name of this outfit
 	pub name: String,
+
+	/// How much thrust this engine produces
 	pub thrust: f32,
+
+	/// The flare sprite this engine creates.
+	/// Its location and size is determined by a ship's
+	/// engine points.
 	pub flare_sprite: String,
 }
 

crates/content/src/gun.rs

@@ -27,24 +27,54 @@ pub(super) mod syntax {
 	}
 }
 
+/// Represents a gun outfit.
 #[derive(Debug, Clone)]
 pub struct Gun {
+	/// The name of this gun
 	pub name: String,
+
+	/// The projectile this gun produces
 	pub projectile: Projectile,
+
+	/// The accuracy of this gun.
+	/// Projectiles can be off center up to
+	/// `spread / 2` degrees in both directions.
+	///
+	/// (Forming a "fire cone" of `spread` degrees)
 	pub spread: Deg<f32>,
+
+	/// Average delay between projectiles, in seconds.
 	pub rate: f32,
+
+	/// Random variation of projectile delay, in seconds.
+	/// Each shot waits (rate += rate_rng).
 	pub rate_rng: f32,
 }
 
+/// Represents a projectile that a [`Gun`] produces.
 #[derive(Debug, Clone)]
 pub struct Projectile {
+	/// The projectile sprite
 	pub sprite: String,
+
+	/// The average size of this projectile
+	/// (height in game units)
 	pub size: f32,
+	/// Random size variation
 	pub size_rng: f32,
+
+	/// The speed of this projectile, in game units / second
 	pub speed: f32,
+	/// Random speed variation
 	pub speed_rng: f32,
+
+	/// The lifespan of this projectile.
+	/// It will vanish if it lives this long without hitting anything.
 	pub lifetime: f32,
+	/// Random lifetime variation
 	pub lifetime_rng: f32,
+
+	/// The damage this projectile does
 	pub damage: f32,
 }
 

crates/content/src/lib.rs

@@ -1,3 +1,8 @@
+#![warn(missing_docs)]
+
+//! This subcrate is responsible for loading, parsing, validating game content,
+//! which is usually stored in `./content`.
+
 mod engine;
 mod gun;
 mod ship;
@@ -39,9 +44,16 @@ trait Build {
 /// Represents generic game content, not connected to any game objects.
 #[derive(Debug)]
 pub struct Content {
+	/// Star systems
 	pub systems: Vec<system::System>,
+
+	/// Ship bodies
 	pub ships: Vec<ship::Ship>,
+
+	/// Gun outfits
 	pub guns: Vec<gun::Gun>,
+
+	/// Engine outfits
 	pub engines: Vec<engine::Engine>,
 }
 
@@ -79,6 +91,7 @@ impl Content {
 		return Ok(());
 	}
 
+	/// Load content from a directory.
 	pub fn load_dir(path: &str) -> Result<Self> {
 		let mut content = Self {
 			systems: Vec::new(),

crates/content/src/ship.rs

@@ -32,24 +32,50 @@ pub(super) mod syntax {
 // Processed data structs.
 // These are exported.
 
+/// Represents a ship chassis.
 #[derive(Debug, Clone)]
 pub struct Ship {
+	/// This ship's name
 	pub name: String,
+
+	/// This ship's sprite
 	pub sprite: String,
+
+	/// The size of this ship.
+	/// Measured as unrotated height,
+	/// in terms of game units.
 	pub size: f32,
+
+	/// Engine points on this ship.
+	/// This is where engine flares are drawn.
 	pub engines: Vec<EnginePoint>,
+
+	/// Gun points on this ship.
+	/// A gun outfit can be mounted on each.
 	pub guns: Vec<GunPoint>,
+
+	/// This ship's hull strength
 	pub hull: f32,
 }
 
+/// An engine point on a ship.
+/// This is where flares are drawn.
 #[derive(Debug, Clone)]
 pub struct EnginePoint {
+	/// This engine point's position, in game units,
+	/// relative to the ship's center.
 	pub pos: Point2<f32>,
+
+	/// The size of the flare that should be drawn
+	/// at this point, measured as height in game units.
 	pub size: f32,
 }
 
+/// A gun point on a ship.
 #[derive(Debug, Clone)]
 pub struct GunPoint {
+	/// This gun point's position, in game units,
+	/// relative to the ship's center.
 	pub pos: Point2<f32>,
 }
 

crates/content/src/system.rs

@@ -77,17 +77,36 @@ pub(super) mod syntax {
 // Processed data structs.
 // These are exported.
 
+/// Represents a star system
 #[derive(Debug)]
 pub struct System {
+	/// This star system's name
 	pub name: String,
+
+	/// Objects in this system
 	pub objects: Vec<Object>,
 }
 
+/// Represents an orbiting body in a star system
+/// (A star, planet, moon, satellite, etc)
+/// These may be landable and may be decorative.
+/// System objects to not interact with the physics engine.
 #[derive(Debug)]
 pub struct Object {
+	/// This object's sprite
 	pub sprite: String,
-	pub position: Point3<f32>,
+
+	/// This object's size.
+	/// Measured as height in game units.
+	/// This value is scaled for distance
+	/// (i.e, the z-value of position)
 	pub size: f32,
+
+	/// This object's position, in game coordinates,
+	/// relative to the system's center (0, 0).
+	pub position: Point3<f32>,
+
+	/// This object's sprite's angle, in degrees.
 	pub angle: Deg<f32>,
 }