Commented up all the code, fixed stopwatch laps, as it was including …

…the time over any stoppages

README.md

@@ -1,10 +1,13 @@
 # Allotment
+"Time is what we want most, but what we use worst."
 
+--------------
 [![Code Climate](https://codeclimate.com/github/benSlaughter/allotment.png)](https://codeclimate.com/github/benSlaughter/allotment)
 [![Build Status](https://travis-ci.org/benSlaughter/allotment.png?branch=master)](https://travis-ci.org/benSlaughter/allotment)
 [![Dependency Status](https://gemnasium.com/benSlaughter/allotment.png)](https://gemnasium.com/benSlaughter/allotment)
 [![Coverage Status](https://coveralls.io/repos/benSlaughter/allotment/badge.png?branch=master)](https://coveralls.io/r/benSlaughter/allotment)
 [![Gem Version](https://badge.fury.io/rb/allotment.png)](http://badge.fury.io/rb/allotment)
+---------------
 
 Allotment is a performance rubygem that records and stores the performance timing of running a block of code,
 or from a from a chosen point, until a task or action is complete.
@@ -109,6 +112,7 @@ result = Allotment.results["my_recording"].first
 ```
 ```ruby
 result = Allotment.results["my_recording"].average
+
 ```
 
 ### Allotment Stopwatches

docs/release_notes.md

@@ -33,11 +33,11 @@
 
 ## Planned Versions
 ### Version 1.1.0
-#### Minor: Simplify, improve, and cleanup allotment
+#### Minor: Simplify, improve, clean
  * Rescue within an event to ensure that the timing is stopped in the event of a failure - *completed*
  * Remove old hooks and add new block management - *completed*
- * Remove and old or unrequired code
+ * Remove and old or unrequired code - *completed*
  * Readme completed with hooks, stopwatches and now functionality
  * 100% coverage rspec tests - *completed* (so far)
- * Complete commenting of code
+ * Complete commenting of code - *completed*
  * Improved method naming - *completed*

lib/allotment.rb

@@ -4,26 +4,53 @@
 require 'allotment/array'
 require 'allotment/stopwatch'
 
+# Allotment
+# "Time is what we want most, but what we use worst."
+#
+# require 'allotment'
+#
+# Allotment.record 'my_event' do
+#   # code here
+# end
+#
+# Allotment.start 'my_event'
+# # code here
+# Allotment.stop 'my_event'
+#
 module Allotment
   @watches = Hashie::Mash.new
   @results = Hashie::Mash.new
 
+  # Allotment module methods
   class << self
-    def on_start(&block)
+    # Called when a recording is started
+    # @returns [Proc] the stored request proc
+    #
+    def on_start &block
       block_given? ? @on_start = block : @on_start
     end
 
-    def on_stop(&block)
+    # Called when a recording is stopped
+    # @returns [Proc] the stored request proc
+    #
+    def on_stop &block
       block_given? ? @on_stop = block : @on_stop
     end
 
+    # Start recording
+    # @param name [String] the name of the event
+    #
     def start name = 'unnamed_recording'
       on_start.call if on_start
       @watches[name] = Stopwatch.new(name).start
     end
 
+    # Stop recording
+    # @param name [String] the name of the event
+    # @raise [NameError] if the recording does not exist
+    #
     def stop name
-      result = @watches.delete(name){ |n| raise NameError, "No recording:" + n }.stop
+      result = @watches.delete(name){ |n| raise NameError, "Unknown recording:" + n }.stop
       on_stop.call if on_stop
 
       # Dealing with the results
@@ -32,6 +59,11 @@ def stop name
       return result
     end
 
+    # Record event
+    # Expects a block to be passed
+    # @param name [String] the name of the event
+    # @yeild [] runs the event
+    #
     def record name = 'unnamed_event'
       start name
       begin
@@ -42,6 +74,9 @@ def record name = 'unnamed_event'
       result
     end
 
+    # Results at that present moment
+    # @return [Hashie::Mash] the  current results
+    #
     def results
       @results
     end

lib/allotment/array.rb

@@ -1,4 +1,7 @@
 class Array
+  # If an array is all numbers
+  # This displayes the mean average
+  #
   def average
     inject(:+).to_f / size
   end

lib/allotment/stopwatch.rb

@@ -1,50 +1,93 @@
 module Allotment
+  # Stopwatch Class
+  # Strangely enough works just like a stopwatch
+  # @!attribure [r] name
+  #   @return [String] the current name
+  # @!attribute [r] status
+  #   @return [String] the current status (running|stopped)
+  #
   class Stopwatch
     attr_reader :name, :status
 
+    # Overwite the obj inspect
+    #
     def inspect
       "#<Stopwatch:%s>" % @status
     end
 
-    def initialize name = nil
-      @name         = name || self.class.uniqe_name
-      @current_time = 0
-      @status       = 'stopped'
+    # If the stopwatch is not given a name the uniqe_name class method is called
+    # @param name [String] choosen name
+    #
+    def initialize name = self.class.uniqe_name
+      @name    = name
+      @status  = 'stopped'
+      @sw_time = 0
     end
 
+    # if the stopwatch was previously stopped
+    # then the current time is removed from the current time
+    # this means that it is in effect added to the total time
+    # @return [Allotment::Stopwatch] self
+    #
     def start
-      @start_time = Time.now - @current_time
+      @last_start = Time.now
+      @lp_start   = Time.now - @lp_time if @lp_time
+      @sw_start   = Time.now - @sw_time
       @status     = 'running'
-      return self
+      self
     end
 
+    # sets the current_time
+    # this is where the start time could be Time.now - current_time
+    # @return [Float] the stopwatch time
+    #
     def stop
-      @status       = 'stopped'
-      @current_time = Time.now - @start_time
+      @status    = 'stopped'
+      @last_stop = Time.now
+      @lp_time   = Time.now - @lp_start if @lp_start
+      @sw_time   = Time.now - @sw_start
     end
 
+    # sets all times to 0
+    # if the timer is running then the start time is just overwritten
+    # if the timer is not then the start time will be over written on start
+    # @return [Allotment::Stopwatch] self
+    #
     def reset
-      @start_time   = Time.now
-      @current_time = 0
+      @sw_start = Time.now
+      @sw_time  = 0
       self
     end
 
+    # A lap is the amount of time from the very start or from the end of the last lap
+    # Accumilated lap time is retained accross any stopages of the stopwatch
+    # @return [Float] the lap time
+    #
     def lap
-      new_lap  = Time.now - (@lap_time || @start_time)
-      @lap_time = Time.now
-      return new_lap
+      new_lap  = Time.now - (@lp_start || @sw_start)
+      @lp_start = Time.now
+      new_lap
     end
 
+    # A split is the amount of time from the last start of the stopwatch
+    # it uses the sw time so it will keep accumelated time accross stoppages
+    # @return [Float] the split time
+    #
     def split
-      Time.now - @start_time
+      @status == 'running' ? Time.now - @last_start : @last_stop - @last_start
     end
 
+    # The accumelated current time on the stopwatch
+    # @return [Float] the current time
+    #
     def time
-      @status == 'running' ? Time.now - @start_time : @current_time
+      @status == 'running' ? Time.now - @sw_start : @sw_time
     end
 
     private
 
+    # ensures that if a stopwatch is unnamed it has a uniqe name
+    # @return [String] stopwatch uniqe name
     def self.uniqe_name
       "stopwatch_" + (@id ? @id += 1 : @id = 0).to_s
     end

spec/allotment_spec.rb

@@ -64,7 +64,7 @@
     end
 
     it "raises an error if the recording does not exist" do
-      expect { Allotment.stop 'my_recording 2.3' }.to raise_error NameError, "No recording:my_recording 2.3"
+      expect { Allotment.stop 'my_recording 2.3' }.to raise_error NameError, "Unknown recording:my_recording 2.3"
     end
 
     it "runs the on_stop block" do