some cleanup and added docs

4 files changed, 38 insertions, 28 deletions

diff --git a/example/src/main.rs b/example/src/main.rs
index c24270d..db7b45a 100644
--- a/example/src/main.rs
+++ b/example/src/main.rs
@@ -14,9 +14,7 @@
 
 extern crate gate;
 
-use gate::{App, AppContext};
-use gate::app_info::AppInfo;
-use gate::input::KeyCode;
+use gate::{App, AppContext, AppInfo, KeyCode};
 use gate::renderer::{Renderer, Affine};
 
 mod asset_id { include!(concat!(env!("OUT_DIR"), "/asset_id.rs")); }
diff --git a/gate/src/app_info.rs b/gate/src/app_info.rs
index 96f0d91..e23d625 100644
--- a/gate/src/app_info.rs
+++ b/gate/src/app_info.rs
@@ -14,21 +14,21 @@
 
 //! Contains `AppInfo` (and related structs), a struct for specifying intialization
 //! information for running an `App`.
-//!
-//! # Example
-//!
-//! ```rust
-//! use gate::app_info::AppInfo;
-//!
-//! let info = AppInfo::with_app_height(100.)
-//!                    .title("My Game")
-//!                    .target_fps(30.)
-//!                    .print_workload_info()
-//!                    .print_gl_info()
-//!                    .build();
-//! ```
 
 /// A struct for specifying initialization information for running an `App`.
+///
+/// # Example
+///
+/// ```rust
+/// use gate::app_info::AppInfo;
+///
+/// let info = AppInfo::with_app_height(100.)
+///                    .title("My Game")
+///                    .target_fps(30.)
+///                    .print_workload_info()
+///                    .print_gl_info()
+///                    .build();
+/// ```
 #[derive(Clone)]
 pub struct AppInfo {
     pub(crate) app_height: f64,
@@ -49,10 +49,10 @@ impl AppInfo {
     /// Even if the window is resized and the aspect ratio changed,
     /// the app height will always remain the same.
     /// The choice of this is important for the `TiledRenderer` in particular.
-    pub fn with_app_height(app_height: f64) -> AppInfoBuilder {
+    pub fn with_app_height(app_height: f64) -> Builder {
         assert!(app_height >= 1e-30 && app_height <= 3000., "unrealistic app height {}", app_height);
 
-        AppInfoBuilder {
+        Builder {
             info: AppInfo {
                 app_height,
                 window_pixels: (800, 600),
@@ -68,11 +68,11 @@ impl AppInfo {
 }
 
 /// Builder for `AppInfo`, created by `AppInfo::builder()`.
-pub struct AppInfoBuilder {
+pub struct Builder {
     info: AppInfo
 }
 
-impl AppInfoBuilder {
+impl Builder {
     /// Specifies the minimum and maximum aspect ratio for the game, enforced by
     /// letterboxing/pillarboxing if necessary (default is `4/3` to `16/9`).
     pub fn aspect_ratio_range(&mut self, min_ratio: f64, max_ratio: f64) -> &mut Self {
diff --git a/gate/src/lib.rs b/gate/src/lib.rs
index 0a1657d..9479125 100644
--- a/gate/src/lib.rs
+++ b/gate/src/lib.rs
@@ -59,18 +59,19 @@ extern crate byteorder;
 pub mod asset_id;
 pub mod renderer;
 pub mod app_info;
-pub mod input;
+mod input;
 mod core;
 
 pub use core::*;
 
+pub use input::KeyCode;
+pub use app_info::AppInfo;
+
 use std::marker::PhantomData;
 
 use core::CoreAudio;
-use ::asset_id::{AppAssetId, IdU16};
-use ::input::KeyCode;
-use ::renderer::Renderer;
-use ::app_info::AppInfo;
+use asset_id::{AppAssetId, IdU16};
+use renderer::Renderer;
 
 /// Invoke this in a `main` method to run the `App`.
 ///
@@ -86,15 +87,19 @@ pub trait App<A: AppAssetId> {
     /// Advances the app state by a given amount of `seconds` (usually a fraction of a second).
     fn advance(&mut self, seconds: f64, ctx: &mut AppContext<A>);
 
+    /// Invoked when a key or mouse button is pressed down.
     fn key_down(&mut self, key: KeyCode, ctx: &mut AppContext<A>);
 
+    /// Invoked when a key or mouse button is released, default behavior is a no-op.
     fn key_up(&mut self, _key: KeyCode, _ctx: &mut AppContext<A>) {}
 
     /// Render the app in its current state.
     fn render(&mut self, renderer: &mut Renderer<A>, ctx: &AppContext<A>);
 }
 
+/// Context passed to methods in `App`.
 pub struct AppContext<A: AppAssetId> {
+    /// Audio playback.
     pub audio: Audio<A>,
     dims: (f64, f64),
     cursor: (f64, f64),
@@ -111,10 +116,17 @@ impl<A: AppAssetId> AppContext<A> {
         }
     }
 
-    pub fn cursor(&self) -> (f64, f64) { self.cursor }
-
+    /// Returns the app (width, height), which are restricted by the app height and the
+    /// aspect ratio range 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`.
+    pub fn cursor(&self) -> (f64, f64) { self.cursor }
+
+    /// Closes the app entirely.
     pub fn close(&mut self) { self.close_requested = true; }
 }
 
diff --git a/gate/src/renderer/renderer.rs b/gate/src/renderer/renderer.rs
index 530f39b..6c15ffc 100644
--- a/gate/src/renderer/renderer.rs
+++ b/gate/src/renderer/renderer.rs
@@ -28,7 +28,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 height of the screen in renderer units ("app pixels") is specified by `AppDims.app_height`.
+/// The dimensions of the screen in renderer units ("app pixels") is `AppContext.dims()`.
 /// The default scaling of each image is such that one source image pixel equals one "app pixel".
 ///
 /// This struct has functions for entering different rendering "modes".