Documenting small things here and there.. (#706)

Documenting small things here and there..

CHANGELOG.md

@@ -3,6 +3,7 @@
 ## Unreleased
 
 ### Added
+
 - [Touch Input][696]
 - [Do not depend on spirv on wasm32 target][689]
 - [Another fast compile flag for macOS][552]
@@ -26,7 +27,6 @@
 [649]: https://github.com/bevyengine/bevy/pull/649
 [651]: https://github.com/bevyengine/bevy/pull/651
 
-
 ## Version 0.2.1 (2020-9-20)
 
 ### Fixed
@@ -107,6 +107,7 @@
 - [do not assume font handle is present in assets][490]
 
 ### Internal Improvements
+
 - Many improvements to Bevy's CI [#325][325], [#349][349], [#357][357], [#373][373], [#423][423]
 
 [145]: https://github.com/bevyengine/bevy/pull/145

README.md

@@ -1,4 +1,5 @@
 # [![Bevy](assets/branding/bevy_logo_light_small.svg)](https://bevyengine.org)
+
 [![Crates.io](https://img.shields.io/crates/v/bevy.svg)](https://crates.io/crates/bevy)
 [![license](https://img.shields.io/badge/license-MIT-blue.svg)](https://github.com/bevyengine/bevy/blob/master/LICENSE)
 [![Crates.io](https://img.shields.io/crates/d/bevy.svg)](https://crates.io/crates/bevy)
@@ -14,9 +15,9 @@ Bevy is still in the _very_ early stages of development. APIs can and will chang
 
 ## Design Goals
 
-* **Capable**: Offer a complete 2D and 3D feature set 
+* **Capable**: Offer a complete 2D and 3D feature set
 * **Simple**: Easy for newbies to pick up, but infinitely flexible for power users
-* **Data Focused**: Data-oriented architecture using the Entity Component System paradigm 
+* **Data Focused**: Data-oriented architecture using the Entity Component System paradigm
 * **Modular**: Use only what you need. Replace what you don't like
 * **Fast**: App logic should run quickly, and when possible, in parallel
 * **Productive**: Changes should compile quickly ... waiting isn't fun
@@ -29,10 +30,11 @@ Bevy is still in the _very_ early stages of development. APIs can and will chang
 
 ## Docs
 
-* **[The Bevy Book](https://bevyengine.org/learn/book/introduction):** Bevy's official documentation. The best place to start learning Bevy. 
+* **[The Bevy Book](https://bevyengine.org/learn/book/introduction):** Bevy's official documentation. The best place to start learning Bevy.
 * **[Bevy Rust API Docs](https://docs.rs/bevy):** Bevy's Rust API docs, which are automatically generated from the doc comments in this repo.
 
 ## Community
+
 Before contributing or participating in discussions with the community, you should familiarize yourself with our **[Code of Conduct](https://github.com/bevyengine/bevy/blob/master/CODE_OF_CONDUCT.md)**
 
 * **[Discord](https://discord.gg/gMUk5Ph):** Bevy's official discord server.
@@ -61,7 +63,9 @@ Bevy can be built just fine using default configuration on stable Rust. However
 Bevy has the following [Focus Areas](https://github.com/bevyengine/bevy/labels/focus-area). We are currently focusing our development efforts in these areas and they will receive priority for Bevy developers' time. If you would like to contribute to Bevy, you are heavily encouraged to join in on these efforts:
 
 ### [Editor-Ready UI](https://github.com/bevyengine/bevy/issues/254)
+
 ### [PBR / Clustered Forward Rendering](https://github.com/bevyengine/bevy/issues/179)
+
 ### [Scenes](https://github.com/bevyengine/bevy/issues/255)
 
 ## Libraries Used
@@ -81,4 +85,4 @@ This [list][cargo_features] outlines the different cargo features supported by B
 
 ## Thanks and Alternatives
 
-Additionally, we would like to thank the [Amethyst](https://github.com/amethyst/amethyst), [macroquad](https://github.com/not-fl3/macroquad), [coffee](https://github.com/hecrj/coffee), [ggez](https://github.com/ggez/ggez), [rg3d](https://github.com/mrDIMAS/rg3d), and [Piston](https://github.com/PistonDevelopers/piston) projects for providing solid examples of game engine development in Rust. If you are looking for a Rust game engine, it is worth considering all of your options. Each engine has different design goals and some will likely resonate with you more than others. 
+Additionally, we would like to thank the [Amethyst](https://github.com/amethyst/amethyst), [macroquad](https://github.com/not-fl3/macroquad), [coffee](https://github.com/hecrj/coffee), [ggez](https://github.com/ggez/ggez), [rg3d](https://github.com/mrDIMAS/rg3d), and [Piston](https://github.com/PistonDevelopers/piston) projects for providing solid examples of game engine development in Rust. If you are looking for a Rust game engine, it is worth considering all of your options. Each engine has different design goals and some will likely resonate with you more than others.

crates/bevy_app/src/app_builder.rs

@@ -221,6 +221,7 @@ impl AppBuilder {
             .add_system_to_stage(stage::EVENT, Events::<T>::update_system.system())
     }
 
+    /// Adds a resource to the current [App] and overwrites any resource previously added of the same type.
     pub fn add_resource<T>(&mut self, resource: T) -> &mut Self
     where
         T: Send + Sync + 'static,

crates/bevy_asset/src/loader.rs

@@ -168,7 +168,7 @@ impl<T: Resource> Default for AssetLifecycleChannel<T> {
     }
 }
 
-/// Reads [AssetResult]s from an [AssetChannel] and updates the [Assets] collection and [LoadState] accordingly
+/// Updates the [Assets] collection according to the changes queued up by [AssetServer].
 pub fn update_asset_storage_system<T: Asset + AssetDynamic>(
     asset_server: Res<AssetServer>,
     mut assets: ResMut<Assets<T>>,

crates/bevy_core/src/time/timer.rs

@@ -34,6 +34,7 @@ impl Timer {
         }
     }
 
+    /// Advances the timer by `delta` seconds.
     pub fn tick(&mut self, delta: f32) {
         let prev_finished = self.elapsed >= self.duration;
         if !prev_finished {

docs/cargo_features.md

@@ -19,14 +19,16 @@ GUI support.
 Make use of GPU via [WebGPU](https://gpuweb.github.io/gpuweb/) support.
 
 ### render
+
 The render pipeline and all render related plugins.
 
 ### dynamic_plugins
+
 Plugins for dynamic loading (libloading)
 
-### png 
+### png
 
-PNG picture format support. 
+PNG picture format support.
 
 ### hdr
 
@@ -58,10 +60,10 @@ FLAC audio fromat support. It's included in bevy_audio feature.
 
 WAV audio format support.
 
-### vorbis 
+### vorbis
 
 Vorbis audio format support.
 
 ### wayland
 
-Enable this to use Wayland display server protocol other than X11.
+Enable this to use Wayland display server protocol other than X11.

docs/debugging.md

@@ -12,6 +12,7 @@
 When a suspected wgpu error occurs, you should capture a wgpu trace so that Bevy and wgpu devs can debug using the [wgpu player tool](https://github.com/gfx-rs/wgpu/wiki/Debugging-wgpu-Applications#tracing-infrastructure).
 
 To capture a wgpu trace:
+
 1. Create a new `wgpu_trace` folder in the root of your cargo workspace
 2. Add the "wgpu_trace" feature to the bevy crate. (ex: `cargo run --example features wgpu_trace`)
-3. Zip up the wgpu_trace folder and attach it to the relevant issue. New wgpu issues should generally be created here https://github.com/gfx-rs/wgpu. Please include the wgpu revision in your bug reports. You can find the revision in the Cargo.lock file in your workspace.
+3. Zip up the wgpu_trace folder and attach it to the relevant issue. New wgpu issues should generally be created [here](https://github.com/gfx-rs/wgpu). Please include the wgpu revision in your bug reports. You can find the revision in the Cargo.lock file in your workspace.

docs/linux_dependencies.md

@@ -5,26 +5,31 @@ This page lists the required dependencies to build a Bevy project on your Linux
 If you don't see your distro present in the list, feel free to add the instructions in this document.
 
 ## Ubuntu 20.04
+
 ```bash
 sudo apt-get install pkg-config libx11-dev libasound2-dev libudev-dev
 ```
 
 ## Fedora 32
+
 ```bash
 sudo dnf install gcc-c++ libX11-devel alsa-lib-devel systemd-devel
 ```
 
 ## Arch / Manjaro
+
 ```bash
 sudo pacman -S libx11 pkgconf alsa-lib
 ```
 
 ## Solus
+
 ```bash
 sudo eopkg install pkg-config libx11-devel g++ alsa-lib-devel
 ```
 
 ## Void
+
 ```bash
 sudo xbps-install -S pkgconf alsa-lib-devel libX11-devel eudev-libudev-devel
 ```

docs/profiling.md

@@ -2,8 +2,8 @@
 
 * Compile Times: append ```-Ztimings``` to cargo builds
 * Runtime Flame Graph:
-    * Flat-ish: ```RUSTFLAGS='-C force-frame-pointers=y' cargo flamegraph --example EXAMPLE_NAME```
-    * Graph: ```RUSTFLAGS='-C force-frame-pointers=y' cargo flamegraph -c "record -g" --example EXAMPLE_NAME```
-    * built on top of perf, no instrumentation required
+  * Flat-ish: ```RUSTFLAGS='-C force-frame-pointers=y' cargo flamegraph --example EXAMPLE_NAME```
+  * Graph: ```RUSTFLAGS='-C force-frame-pointers=y' cargo flamegraph -c "record -g" --example EXAMPLE_NAME```
+  * built on top of perf, no instrumentation required
 * Runtime Instrumentation:
-    * https://github.com/glennw/thread_profiler
+  * [thread_profiler](https://github.com/glennw/thread_profiler)

src/lib.rs

@@ -26,9 +26,9 @@
 //! and it gets more powerful every day!
 //!
 //! ### This Crate
-//! The "bevy" crate is just a container crate that makes it easier to consume Bevy components.
+//! The `bevy` crate is just a container crate that makes it easier to consume Bevy components.
 //! The defaults provide a "full" engine experience, but you can easily enable / disable features
-//! in your project's Cargo.toml to meet your specific needs. See Bevy's Cargo.toml for a full list of features available.
+//! in your project's `Cargo.toml` to meet your specific needs. See Bevy's `Cargo.toml` for a full list of features available.
 //!
 //! If you prefer it, you can also consume the individual bevy crates directly.