updated rustdoc comments

5 files changed, 36 insertions, 14 deletions

diff --git a/gate/src/app_context.rs b/gate/src/app_context.rs
index 45a59d5..be70b5b 100644
--- a/gate/src/app_context.rs
+++ b/gate/src/app_context.rs
@@ -56,18 +56,25 @@ impl<A: AppAssetId> AppContext<A> {
         );
     }
 
-    /// Returns the app (width, height), which are restricted by the app height and the
-    /// aspect ratio range specified in `AppInfo`.
+    /// Returns the app (width, height), which are restricted by the min/max dimensions
+    /// specified in `AppInfo`.
     pub fn dims(&self) -> (f64, f64) { self.dims }
 
     /// Returns the mouse cursor (x, y) position in app coordinates.
     ///
-    /// The x coordinate lies in the range `-0.5 * self.dims().0` to `0.5 * self.dims().0`.
-    /// The y coordinate lies in the range `-0.5 * self.dims().1` to `0.5 * self.dims().1`.
+    /// The x coordinate lies in the range `0` to `self.dims().0`.
+    /// The y coordinate lies in the range `0` to `self.dims().1`.
     pub fn cursor(&self) -> (f64, f64) { self.cursor }
 
+    /// Returns the width of a native pixel, measured in "app pixels".
+    ///
+    /// This value will always be at most 1.
     pub fn native_px(&self) -> f64 { self.native_px }
 
+    /// Convenience method for aligning an `(x, y)` position to native pixels.
+    ///
+    /// This is typically used to align a camera position.
+    /// See also `self.native_px()`.
     pub fn native_px_align(&self, x: f64, y: f64) -> (f64, f64) {
         (
             (x / self.native_px).round() * self.native_px,
diff --git a/gate/src/app_info.rs b/gate/src/app_info.rs
index e9ecaa6..90dc1e7 100644
--- a/gate/src/app_info.rs
+++ b/gate/src/app_info.rs
@@ -44,12 +44,17 @@ pub struct AppInfo {
     pub(crate) print_gl_info: bool,
 }
 
-// FIXME update rustdoc comments relating to app dims...
-
 impl AppInfo {
+    /// Returns a new `AppInfo`, initialized with the maximum app dimensions.
+    ///
+    /// These dimensions are specified in conceptual "app pixels",
+    /// which defines the units used by the renderers.
+    /// Even if a window is resized, this conecptual `max_width` and `max_height`
+    /// will never be exceeded.
+    /// Max width/height must be at least 1.
     pub fn with_max_dims(max_width: f64, max_height: f64) -> AppInfo {
-        assert!(max_width >= 1e-30 && max_width <= 3000., "unrealistic max_width: {}", max_width);
-        assert!(max_height >= 1e-30 && max_height <= 3000., "unrealistic max_height: {}", max_height);
+        assert!(max_width >= 1. && max_width <= 3000., "unrealistic max_width: {}", max_width);
+        assert!(max_height >= 1. && max_height <= 3000., "unrealistic max_height: {}", max_height);
         AppInfo {
             window_pixels: (800, 600),
             min_dims: (0., 0.),
@@ -62,12 +67,23 @@ impl AppInfo {
         }
     }
 
+    /// Specifies the minimum dimensions in "app pixels" (default is 0).
+    ///
+    /// Even if you want height to be fixed, it is good practice to design the app so that
+    /// min_height is slightly less than max_height.
+    /// Under normal circumstances, the app dimensions will not fall below these minimum
+    /// dimensions, but there are some extreme cases in which it could.
+    /// App dimensions will never fall below 1.
     pub fn min_dims(mut self, min_width: f64, min_height: f64) -> Self {
         assert!(self.min_dims.0 <= self.max_dims.0 && self.min_dims.1 <= self.max_dims.1);
         self.min_dims = (min_width, min_height);
         self
     }
 
+    /// Specifies the tile width for meshing tiles.
+    ///
+    /// If this value is set, the app dimensions are chosen carefully to ensure that
+    /// the width of a tile is aligned to native pixels.
     pub fn tile_width(mut self, tile_width: u32) -> Self {
         assert!(tile_width > 0 && tile_width <= 10000, "unrealistic tile_width {}", tile_width);
         self.tile_width = Some(tile_width);
@@ -77,8 +93,8 @@ impl AppInfo {
     /// Specifies a window title (default is "untitled app").
     pub fn title(mut self, title: &'static str) -> Self { self.title = title; self }
 
-    /// Specifies the intial width and height of the window (default is width `800` height `600`).
-    pub fn window_pixels(mut self, width: u32, height: u32) -> Self {
+    /// Specifies the intial native width and height of the window (default is `800` by `600`).
+    pub fn native_dims(mut self, width: u32, height: u32) -> Self {
         assert!(width >= 10 && width <= 3000, "unrealistic window width {}", width);
         assert!(height >= 10 && height <= 3000, "unrealistic window height {}", height);
         self.window_pixels = (width, height);
diff --git a/gate/src/asset_id.rs b/gate/src/asset_id.rs
index 9052325..2067d9d 100644
--- a/gate/src/asset_id.rs
+++ b/gate/src/asset_id.rs
@@ -16,7 +16,7 @@
 //!
 //! The user is not expected to implement these traits themselves directly.
 //! Rather, the generated code from "gate_build" will implement these traits.
-//! Gate build will generate four enums: `SpriteId`, `TileId`, `MusicId`, and `SoundId`,
+//! Gate build will generate four enums: `SpriteId`, `MusicId`, and `SoundId`,
 //! that implement `IdU16`.
 //! It will also generate a collection type `AssetId` that implements `AppAssetId`.
 
diff --git a/gate/src/renderer/renderer.rs b/gate/src/renderer/renderer.rs
index f9c7760..6cc837d 100644
--- a/gate/src/renderer/renderer.rs
+++ b/gate/src/renderer/renderer.rs
@@ -27,7 +27,7 @@ use super::core_renderer::CoreRenderer;
 
 /// Contains methods for rendering visuals to screen.
 ///
-/// The renderer origin is the center of the screen, with +X meaning "right" and +Y meaning "up".
+/// The renderer origin is the bottom-left of the screen, with +X meaning "right" and +Y meaning "up".
 /// The dimensions of the screen in renderer units ("app pixels") are `AppContext.dims()`.
 /// The default scaling of each image is such that one source image pixel equals one "app pixel".
 ///
diff --git a/gate_build/src/lib.rs b/gate_build/src/lib.rs
index d324db6..d30770a 100644
--- a/gate_build/src/lib.rs
+++ b/gate_build/src/lib.rs
@@ -21,8 +21,7 @@
 //! # Example build script
 //!
 //! In the below example, the user should place sprite png files in the "sprites" directory,
-//! tile png files in the "tiles" directory, music ogg files in the "music" directory,
-//! and sound ogg files in the "sounds" directory.
+//! music ogg files in the "music" directory, and sound ogg files in the "sounds" directory.
 //!
 //! ```rust,no_run
 //! extern crate gate_build;