From e093a3243b6527ebb94b864dea3291fef5261bc4 Mon Sep 17 00:00:00 2001
From: Carter Anderson <mcanders1@gmail.com>
Date: Sun, 17 May 2020 10:29:42 -0700
Subject: [PATCH] phrasing tweaks

---
 Cargo.toml                            |  4 ++--
 crates/bevy_asset/src/asset_server.rs |  1 +
 examples/asset/asset_loading.rs       |  9 +++++----
 examples/asset/hot_asset_reload.rs    | 13 +++++++------
 4 files changed, 15 insertions(+), 12 deletions(-)

diff --git a/Cargo.toml b/Cargo.toml
index 9f4c62f88c..7f7dc3137a 100644
--- a/Cargo.toml
+++ b/Cargo.toml
@@ -112,8 +112,8 @@ name = "plugin"
 path = "examples/app/plugin.rs"
 
 [[example]]
-name = "hot_asset_reload"
-path = "examples/asset/hot_asset_reload.rs"
+name = "hot_asset_reloading"
+path = "examples/asset/hot_asset_reloading.rs"
 
 [[example]]
 name = "asset_loading"
diff --git a/crates/bevy_asset/src/asset_server.rs b/crates/bevy_asset/src/asset_server.rs
index 9ed95f8e8d..27a2bff273 100644
--- a/crates/bevy_asset/src/asset_server.rs
+++ b/crates/bevy_asset/src/asset_server.rs
@@ -206,6 +206,7 @@ impl AssetServer {
         }
     }
 
+    // TODO: add type checking here. people shouldn't be able to request a Handle<Texture> for a Mesh asset
     pub fn load<T, P: AsRef<Path>>(&self, path: P) -> Result<Handle<T>, AssetServerError> {
         self.load_untyped(path)
             .map(|handle_id| Handle::from(handle_id))
diff --git a/examples/asset/asset_loading.rs b/examples/asset/asset_loading.rs
index 18a765d7a4..30f2961aa7 100644
--- a/examples/asset/asset_loading.rs
+++ b/examples/asset/asset_loading.rs
@@ -14,7 +14,7 @@ fn setup(
     mut meshes: ResMut<Assets<Mesh>>,
     mut materials: ResMut<Assets<StandardMaterial>>,
 ) {
-    // You can load all assets in a folder like this. they will be loaded in parallel without blocking
+    // You can load all assets in a folder like this. They will be loaded in parallel without blocking
     asset_server.load_asset_folder("assets/models/monkey").unwrap();
 
     // Then any asset in the folder can be accessed like this:
@@ -27,19 +27,20 @@ fn setup(
         .load("assets/models/cube/cube.gltf")
         .unwrap();
    
-    // Assets are loaded in the background by default, which means they might not be available immediately after loading.
+    // Assets are loaded in the background by default, which means they might not be available immediately after calling load().
     // If you need immediate access you can load assets synchronously like this:
     let sphere_handle = asset_server.load_sync(&mut meshes, "assets/models/sphere/sphere.gltf").unwrap();
+    // All assets end up in their Assets<T> collection once they are done loading:
     let sphere = meshes.get(&sphere_handle).unwrap();
     println!("{:?}", sphere.primitive_topology);
 
-    // You can also add assets directly to their Assets<T> storage
+    // You can also add assets directly to their Assets<T> storage:
     let material_handle = materials.add(StandardMaterial {
         albedo: Color::rgb(0.5, 0.4, 0.3),
         ..Default::default()
     });
 
-    // add entities to the world
+    // Add entities to the world:
     command_buffer
         .build()
         // monkey
diff --git a/examples/asset/hot_asset_reload.rs b/examples/asset/hot_asset_reload.rs
index 922bb4ec52..19f88233ef 100644
--- a/examples/asset/hot_asset_reload.rs
+++ b/examples/asset/hot_asset_reload.rs
@@ -15,26 +15,27 @@ fn setup(
     mut asset_server: ResMut<AssetServer>,
     mut materials: ResMut<Assets<StandardMaterial>>,
 ) {
-    // load an asset folder
+    // Load an asset folder:
     asset_server.load_asset_folder("assets").unwrap();
 
-    // tell the asset server to watch for changes
+    // Tell the asset server to watch for asset changes on disk:
     asset_server.watch_for_changes().unwrap();
 
-    // load the mesh
+    // Get a handle for our mesh:
     let mesh_handle = asset_server
         .get_handle("assets/models/monkey/Monkey.gltf")
         .unwrap();
 
-    // now any changes to the mesh will be reloaded automatically!
+    // Any changes to the mesh will be reloaded automatically! Try making a change to Monkey.gltf.
+    // You should see the changes immediately show up in your app.
 
-    // create a material for the mesh
+    // Create a material for the mesh:
     let material_handle = materials.add(StandardMaterial {
         albedo: Color::rgb(0.5, 0.4, 0.3),
         ..Default::default()
     });
 
-    // add entities to the world
+    // Add entities to the world:
     command_buffer
         .build()
         // mesh