Merge pull request #98 from wooferzfg/doc-fix

Fix documentation issues & add comments to describe tests

src/component/blank_space.rs

@@ -1,5 +1,5 @@
 //! Provides the Blank Space Component and relevant types for using it. The
-//! Blank Space Component is simply an empty component, that doesn't show
+//! Blank Space Component is simply an empty component that doesn't show
 //! anything other than a background. It mostly serves as padding between other
 //! components.
 
@@ -9,7 +9,7 @@ use std::io::Write;
 use std::borrow::Cow;
 use settings::{Field, Gradient, SettingsDescription, Value};
 
-/// The Blank Space Component is simply an empty component, that doesn't show
+/// The Blank Space Component is simply an empty component that doesn't show
 /// anything other than a background. It mostly serves as padding between other
 /// components.
 #[derive(Default, Clone)]

src/component/current_comparison.rs

@@ -1,6 +1,6 @@
 //! Provides the Current Comparison Component and relevant types for using it.
 //! The Current Comparison Component is a component that shows the name of the
-//! comparison that is currently selected for being compared against.
+//! comparison that is currently selected to be compared against.
 
 use Timer;
 use serde_json::{to_writer, Result};
@@ -10,7 +10,7 @@ use settings::{Color, Field, Gradient, SettingsDescription, Value};
 use super::DEFAULT_INFO_TEXT_GRADIENT;
 
 /// The Current Comparison Component is a component that shows the name of the
-/// comparison that is currently selected for being compared against.
+/// comparison that is currently selected to be compared against.
 #[derive(Default, Clone)]
 pub struct Component {
     settings: Settings,

src/component/detailed_timer.rs

@@ -1,8 +1,8 @@
 //! Provides the Detailed Timer Component and relevant types for using it. The
 //! Detailed Timer Component is a component that shows two timers, one for the
 //! total time of the current attempt and one showing the time of just the
-//! current segment. Other information like segment times of up to two
-//! comparisons, the segment icon and the segment's name can also be shown.
+//! current segment. Other information, like segment times of up to two
+//! comparisons, the segment icon, and the segment's name, can also be shown.
 
 use {GeneralLayoutSettings, TimeSpan, Timer, TimerPhase, TimingMethod};
 use super::timer;
@@ -16,8 +16,8 @@ use settings::{Field, Gradient, SemanticColor, SettingsDescription, Value};
 
 /// The Detailed Timer Component is a component that shows two timers, one for
 /// the total time of the current attempt and one showing the time of just the
-/// current segment. Other information like segment times of up to two
-/// comparisons, the segment icon and the segment's name can also be shown.
+/// current segment. Other information, like segment times of up to two
+/// comparisons, the segment icon, and the segment's name, can also be shown.
 #[derive(Default, Clone)]
 pub struct Component {
     icon_id: usize,

src/component/previous_segment.rs

@@ -1,10 +1,9 @@
 //! Provides the Previous Segment Component and relevant types for using it. The
 //! Previous Segment Component is a component that shows how much time was saved
-//! or lost based in the last segment based on the chosen comparison.
-//! Additionally the time save that would've been possible in the previous
-//! segment can be displayed. This component switches to a `Live Segment` view
-//! that shows active time loss, whenever the runner is losing time on the
-//! current segment.
+//! or lost during the previous segment based on the chosen comparison.
+//! Additionally, the potential time save for the previous segment can be
+//! displayed. This component switches to a `Live Segment` view that shows
+//! active time loss whenever the runner is losing time on the current segment.
 
 use {analysis, comparison, GeneralLayoutSettings, Timer, TimerPhase};
 use time::formatter::{Accuracy, Delta, PossibleTimeSave, TimeFormatter};
@@ -16,11 +15,10 @@ use settings::{Color, Field, Gradient, SemanticColor, SettingsDescription, Value
 use super::DEFAULT_INFO_TEXT_GRADIENT;
 
 /// The Previous Segment Component is a component that shows how much time was
-/// saved or lost based in the last segment based on the chosen comparison.
-/// Additionally the time save that would've been possible in the previous
-/// segment can be displayed. This component switches to a `Live Segment` view
-/// that shows active time loss, whenever the runner is losing time on the
-/// current segment.
+/// saved or lost during the previous segment based on the chosen comparison.
+/// Additionally, the potential time save for the previous segment can be
+/// displayed. This component switches to a `Live Segment` view that shows
+/// active time loss whenever the runner is losing time on the current segment.
 #[derive(Default, Clone)]
 pub struct Component {
     settings: Settings,

src/component/splits.rs

@@ -1,7 +1,7 @@
 //! Provides the Splits Component and relevant types for using it. The Splits
 //! Component is the main component for visualizing all the split times. Each
 //! segment is shown in a tabular fashion showing the segment icon, segment
-//! name, the delta compared to the chosen comparison and the split time. The
+//! name, the delta compared to the chosen comparison, and the split time. The
 //! list provides scrolling functionality, so not every segment needs to be
 //! shown all the time.
 
@@ -17,7 +17,7 @@ use settings::{Color, Field, Gradient, SemanticColor, SettingsDescription, Value
 
 /// The Splits Component is the main component for visualizing all the split
 /// times. Each segment is shown in a tabular fashion showing the segment icon,
-/// segment name, the delta compared to the chosen comparison and the split
+/// segment name, the delta compared to the chosen comparison, and the split
 /// time. The list provides scrolling functionality, so not every segment needs
 /// to be shown all the time.
 #[derive(Default, Clone)]
@@ -39,8 +39,8 @@ pub struct Settings {
     pub visual_split_count: usize,
     /// If there's more segments than segments that are shown, the window
     /// showing the segments automatically scrolls up and down when the current
-    /// segment changes. This count determines how many future segments are at
-    /// least to be shown in this scrolling window, when it automatically
+    /// segment changes. This count determines the minimum number of future
+    /// segments to be shown in this scrolling window when it automatically
     /// scrolls.
     pub split_preview_count: usize,
     /// If not every segment is shown in the scrolling window of segments, then

src/component/sum_of_best.rs

@@ -1,5 +1,5 @@
 //! Provides the Sum of Best Segments Component. The Sum of Best Segments
-//! Component shows the fastest time possible to complete a run of this
+//! Component shows the fastest possible time to complete a run of this
 //! category, based on information collected from all the previous attempts.
 //! This often matches up with the sum of the best segment times of all the
 //! segments, but that may not always be the case, as skipped segments may
@@ -16,7 +16,7 @@ use std::borrow::Cow;
 use settings::{Color, Field, Gradient, SettingsDescription, Value};
 use super::DEFAULT_INFO_TEXT_GRADIENT;
 
-/// The Sum of Best Segments Component shows the fastest time possible to
+/// The Sum of Best Segments Component shows the fastest possible time to
 /// complete a run of this category, based on information collected from all the
 /// previous attempts. This often matches up with the sum of the best segment
 /// times of all the segments, but that may not always be the case, as skipped

src/component/title/mod.rs

@@ -1,7 +1,7 @@
 //! Provides the Title Component and relevant types for using it. The Title
 //! Component is a component that shows the name of the game and the category
-//! that is being run. Additionally the game's icon, the attempt count and the
-//! amount of successfully finished attempts can be shown.
+//! that is being run. Additionally, the game icon, the attempt count, and the
+//! total number of finished runs can be shown.
 
 use {Timer, TimerPhase};
 use serde_json::{to_writer, Result};
@@ -13,8 +13,8 @@ use settings::{Alignment, Color, Field, Gradient, SettingsDescription, Value};
 mod tests;
 
 /// The Title Component is a component that shows the name of the game and the
-/// category that is being run. Additionally the game's icon, the attempt count
-/// and the amount of successfully finished attempts can be shown.
+/// category that is being run. Additionally, the game icon, the attempt count,
+/// and the total number of finished runs can be shown.
 #[derive(Default, Clone)]
 pub struct Component {
     icon_id: usize,

src/layout/general_settings.rs

@@ -9,10 +9,10 @@ pub struct GeneralSettings {
     /// The color to use for when the runner achieved a best segment.
     pub best_segment_color: Color,
     /// The color to use for when the runner is ahead of the comparison and is
-    /// also gaining even more time.
+    /// gaining even more time.
     pub ahead_gaining_time_color: Color,
     /// The color to use for when the runner is ahead of the comparison, but is
-    /// losing time to the comparison.
+    /// losing time.
     pub ahead_losing_time_color: Color,
     /// The color to use for when the runner is behind the comparison, but is
     /// gaining back time.

src/run/editor/cleaning.rs

@@ -1,9 +1,10 @@
 //! The cleaning module provides the Sum of Best Cleaner which allows you to
 //! interactively remove potential issues in the Segment History that lead to an
-//! inaccurate Sum of Best. If you skip a split, whenever you will do the next
+//! inaccurate Sum of Best. If you skip a split, whenever you get to the next
 //! split, the combined segment time might be faster than the sum of the
-//! individual best segments. The Sum of Best Cleaner will point out all of
-//! these and allows you to delete them individually if any of them seem wrong.
+//! individual best segments. The Sum of Best Cleaner will point out all
+//! occurrences of this and allows you to delete them individually if any of
+//! them seem wrong.
 
 use {Attempt, Run, Segment, TimeSpan, TimingMethod};
 use analysis::sum_of_segments::{best, track_branch};
@@ -14,9 +15,9 @@ use chrono::Local;
 
 /// A Sum of Best Cleaner allows you to interactively remove potential issues in
 /// the Segment History that lead to an inaccurate Sum of Best. If you skip a
-/// split, whenever you will do the next split, the combined segment time might
+/// split, whenever you get to the next split, the combined segment time might
 /// be faster than the sum of the individual best segments. The Sum of Best
-/// Cleaner will point out all of these and allows you to delete them
+/// Cleaner will point out all occurrences of this and allows you to delete them
 /// individually if any of them seem wrong.
 pub struct SumOfBestCleaner<'r> {
     run: &'r mut Run,

src/run/editor/state.rs

@@ -17,10 +17,10 @@ pub struct State {
     pub game: String,
     /// The name of the category the Run is for.
     pub category: String,
-    /// The timer offset specifies the time, the timer starts at when starting a
+    /// The timer offset specifies the time that the timer starts at when starting a
     /// new attempt.
     pub offset: String,
-    /// The amount of times this Run has been attempted for by the runner. This
+    /// The number of times this Run has been attempted by the runner. This
     /// is mostly just a visual number and has no effect on any history.
     pub attempts: u32,
     /// The timing method that is currently selected to be visualized and

src/run/segment.rs

@@ -4,7 +4,7 @@ use comparison::personal_best;
 
 /// A Segment describes a point in a speedrun that is suitable for storing a
 /// split time. This stores the name of that segment, an icon, the split times
-/// of different comparisons and a history of segment times.
+/// of different comparisons, and a history of segment times.
 ///
 /// # Examples
 ///

src/settings/semantic_color.rs

@@ -8,11 +8,10 @@ use super::Color;
 pub enum SemanticColor {
     /// There's no meaningful information for this color.
     Default,
-    /// The runner is ahead of the comparison and is also gaining even more
+    /// The runner is ahead of the comparison and is gaining even more
     /// time.
     AheadGainingTime,
-    /// The runner is ahead of the comparison, but is losing time to the
-    /// comparison.
+    /// The runner is ahead of the comparison, but is losing time.
     AheadLosingTime,
     /// The runner is behind the comparison and is losing even more time.
     BehindLosingTime,

src/time/formatter/accuracy.rs

@@ -4,9 +4,9 @@
 pub enum Accuracy {
     /// Don't show any fractional part.
     Seconds,
-    /// Show the tenths of the times (12:34.5).
+    /// Show tenths of a second (12:34.5).
     Tenths,
-    /// Show the hundredths of the times (12:34.56).
+    /// Show hundredths of a second (12:34.56).
     Hundredths,
 }