workpattern 0.3.0 → 0.3.1

data/lib/workpattern/day.rb

@@ -1,13 +1,33 @@
 module Workpattern
-  # Represents the 24 hours of a day using module <tt>hour</tt>
+  
+  # @author Barrie Callender
+  # @!attribute values
+  #   @return [Array] each hour of the day
+  # @!attribute hours
+  #   @return [Integer] number of hours in the day
+  # @!attribute first_hour
+  #   @return [Integer] first working hour in the day
+  # @!attribute first_min
+  #   @return [Integer] first working minute in first working hour in the day
+  # @!attribute last_hour
+  #   @return [Integer] last working hour in the day
+  # @!attribute last_min
+  #   @return [Integer] last working minute in last working hour in the day
+  # @!attribute total
+  #   @return [Integer] total number of minutes in the day
+  #  
+  # Represents the 24 hours of a day.
+  #
+  # @since 0.2.0
+  # @todo implement a day with different number of hours in it to support daylight saving
   #
   class Day
     include Workpattern::Utility
     attr_accessor :values, :hours, :first_hour, :first_min, :last_hour, :last_min, :total
     
-    # :call-seq: new(type=1) => Day
-    # Creates a 24 hour day defaulting to a working day.
-    # Pass 0 to create a non-working day.
+    # The new <tt>Day</tt> object can be created as either working or resting.
+    #
+    # @param [Integer] type is working (1) or resting (0)
     #
     def initialize(type=1)
       @hours=24
@@ -18,9 +38,10 @@ module Workpattern
       set_attributes
     end
     
-    # :call-seq: duplicate => Day
     # Creates a duplicate of the current <tt>Day</tt> instance.
     #
+    # @return [Day] 
+    #
     def duplicate
       duplicate_day = Day.new()
       duplicate_values=Array.new(@values.size)
@@ -38,21 +59,18 @@ module Workpattern
       return duplicate_day
     end
     
-    # :call-seq: refresh
     # Recalculates characteristics for this day
     #
     def refresh
       set_attributes
     end
     
-    # :call-seq: workpattern(start_time,finish_time,type)
     # Sets all minutes in a date range to be working or resting.
-    # The <tt>start_time</tt> and <tt>finish_time</tt> need to have 
-    # <tt>#hour</tt> and <tt>#min</tt> methods to return the time 
-    # in hours and minutes respectively.
     #
-    # Pass 1 as the <tt>type</tt> for working and 0 for resting.
-    # 
+    # @param [(#hour,#min)] start_time is the start of the range to set
+    # @param [(#hour, #min)] finish_time is the finish of the range to be set
+    # @param [Integer] type is either working (1) or resting (0)
+    #
     def workpattern(start_time,finish_time,type)
     
       if start_time.hour==finish_time.hour
@@ -71,15 +89,22 @@ module Workpattern
       set_attributes
     end
     
-    # :call-seq: calc(time,duration) => time, duration
-    #
     # Calculates the result of adding <tt>duration</tt> to
     # <tt>time</tt>.  The <tt>duration</tt> can be negative in
     # which case it subtracts from <tt>time</tt>.
     #
     # An addition where there are less working minutes left in 
     # the day than are being added will result in the time 
-    # returned having 60 as the value in <tt>min</tt>. 
+    # returned being 00:00 on the following day.
+    #
+    # A subtraction where there are less working minutes left in
+    # the day than are being added will result in the time 
+    # returned being the previous day with the <tt>midnight</tt> flag set to true.
+    #
+    # @param [DateTime] time when the calculation starts from
+    # @param [Integer] duration is the number of minutes to add or subtract if it is negative
+    # @param [Boolean] midnight is a flag used in subtraction to pretend the time is actually midnight
+    # @return [DateTime,Integer,Boolean] Calculated time along with any remaining duration and the midnight flag
     # 
     def calc(time,duration,midnight=false)
     
@@ -93,17 +118,21 @@ module Workpattern
     
     end
     
-    # :call-seq: working?(start) => Boolean
-    # Returns true if the given minute is working and false if it isn't
+    # Returns true if the given minute is working and false if it is resting
+    #
+    # @param [(#hour, #min)] start is the time in the day to inspect
+    # @return [Boolean] true if the time is working and false if it is resting
     #
     def working?(start)
       return true if minutes(start.hour,start.min,start.hour,start.min)==1
       return false
     end
     
-    # :call-seq: diff(start,finish) => Duration, Date
-    # Returns the difference in minutes between two times. if the given 
-    # minute is working and false if it isn't
+    # Returns the difference in working minutes between two times.
+    #
+    # @param [(#hour, #min)] start start time in the range
+    # @param [(#hour, #min)] finish finish time in the range
+    # @return [Integer] number of working minutes
     #
     def diff(start,finish)
       start,finish=finish,start if ((start <=> finish))==1
@@ -120,9 +149,16 @@ module Workpattern
       return duration, start
     end
     
-    # :call-seq: minutes(start_hour,start_min,finish_hour,finish_min) => duration    
-    # Returns the total number of minutes between and including two minutes.
-    # 
+    # Returns the total number of minutes between two times.
+    #
+    # @param [Integer] start_hour first hour in range
+    # @param [Integer] start_min first minute of first hour in range
+    # @param [Integer] finish_hour last hour in range
+    # @param [Integer] finish_min last minute of last hour in range
+    # @return [Integer] minutes between supplied hours and minutes
+    #
+    # @todo can this method and #diff method be combined?
+    #
     def minutes(start_hour,start_min,finish_hour,finish_min)
       
       if (start_hour > finish_hour) || ((finish_hour==start_hour) && (start_min > finish_min))
@@ -146,6 +182,8 @@ module Workpattern
 
     private
     
+    # Calculates the attributes that describe the day.  Called after changes.
+    #
     def set_attributes
       @first_hour=nil
       @first_min=nil
@@ -161,6 +199,12 @@ module Workpattern
       }
     end
     
+    # Returns the first working minute as a <tt>DateTime</tt> or <tt>oo:oo</tt>
+    # when there is no working minutes in the day.  Used by the <tt>#subtract</tt> method
+    #
+    # @param [DateTime] time day for which the first working time is sought.
+    # @return [DateTime] the first working time of the day
+    #
     def first_working_minute(time)
       if @first_hour.nil?
         return time - (HOUR*time.hour) - (MINUTE*time.min)
@@ -171,6 +215,13 @@ module Workpattern
       end  
     end
     
+    # Handles the subtraction of a duration from a time in the day.
+    # 
+    # @param [DateTime] time when the subtraction starts from
+    # @param [Integer] duration is the number of minutes to subtract from the <tt>time</tt>
+    # @param [Boolean] midnight is a flag used in subtraction to pretend the time is actually midnight
+    # @return [DateTime,Integer,Boolean] Calculated time along with any remaining duration and the midnight flag
+    #
     def subtract(time,duration,midnight=false)    
       if (time.hour==0 && time.min==0)
         if midnight      
@@ -213,10 +264,13 @@ module Workpattern
       return time,duration, false
     end
     
-    # 
-    # Returns the result of adding #duration to the specified time
+    # Returns the result of adding <tt>duration</tt> to the given <tt>time</tt>
     # When there are not enough minutes in the day it returns the date
-    # for the start of the following
+    # for the start of the following day.
+    #
+    # @param [DateTime] time when the calculation starts from
+    # @param [Integer] duration is the number of minutes to add
+    # @return [DateTime,Integer] Calculated time along with any remaining duration
     #
     def add(time,duration)
       available_minutes=minutes(time.hour,time.min,@hours-1,59)   
@@ -245,16 +299,26 @@ module Workpattern
       return result_date,duration, false
     end
     
+    # Returns the start of the next hour.
+    #
+    # The next hour could be the start of the following day.
+    #
+    # @param [DateTime] start is the <tt>DateTime</tt> for which the following hour is required.
+    # @return [DateTime] the start of the next hour following the <tt>DateTime</tt> supplied
+    #
     def next_hour(start)
       return start+HOUR-(start.min*MINUTE) 
     end
     
+    # Returns the number of working minutes left in the current hour
+    #
+    # @param [DateTime] start is the <tt>DateTime</tt> for which the remaining working minutes 
+    #                   in the hour are required
+    # @return [Integer] number of remaining working minutes
+    #
     def minutes_left_in_hour(start)
       return @values[start.hour].diff(start.min,60)
     end
     
-    def minutes_left_in_day(start)
-      start.hour
-    end  
   end
 end

data/lib/workpattern/hour.rb

@@ -1,60 +1,76 @@
 module Workpattern
   
-  # Represents the 60 minutes of an hour using a <tt>Fixnum</tt> or <tt>Bignum</tt>
+  # Represents the 60 minutes of an hour using an <tt>Integer</tt>
+  #
+  # @since 0.2.0
   #
   module Hour
  
-    # :call-seq: total => Integer
     # Returns the total working minutes in the hour
-    # 
+    #
+    # @return [Integer] working minutes in the hour 
+    #
     def total
       return minutes(0,59)
     end  
     
-    # :call-seq: workpattern(start,finish,type) => Fixnum
     # Sets the minutes to either working (type=1) or resting (type=0)
+    # 
+    # @param [Integer] start minute at start of range
+    # @param [Integer] finish minute at end of range
+    # @param [Integer] type defines whether working (1) or resting (0)
     #
     def workpattern(start,finish,type)
       return working(start,finish) if type==1
       return resting(start,finish) if type==0
     end
     
-    # :call-seq: first => Integer
-    # Returns the first working minute in the hour or 60 if there are none
+    # Returns the first working minute in the hour or 60 if there are no working minutes
+    #
+    # @return [Integer] first working minute or 60 if none found
     #
     def first
       0.upto(59) {|minute| return minute if self.minutes(minute,minute)==1}
       return nil
     end
     
-    # :call-seq: last => Integer
-    # Returns the last working minute in the hour or -1 if there are none
+    # Returns the last working minute in the hour or nil if there are no working minutes
+    #
+    # @return [Integer] last working minute or nil if none found
     #
     def last
       59.downto(0) {|minute| return minute if self.minutes(minute,minute)==1}
       return nil
     end
     
-    # :call-seq: working?(start) => Boolean
     # Returns true if the given minute is working and false if it isn't
+    # 
+    # @param [Integer] start is the minute being tested
+    # @return [Boolean] true if minute is working, otherwise false
     #
     def working?(start)
       return true if minutes(start,start)==1
       return false
     end
     
-    # :call-seq: minutes(start,finish) => Integer
     # Returns the total number of minutes between and including two minutes
     #
+    # @param [Integer] start first minute in range
+    # @param [Integer] finish last minute in range
+    # @return [Integer] number of minutes from <tt>start</tt> to <tt>finish</tt> inclusive
+    #
     def minutes(start,finish)
       start,finish=finish,start if start > finish
       return (self & mask(start,finish)).to_s(2).count('1')
     end
     
-    # :call-seq: calc(datetime,duration) => DateTime, Integer
-    # Returns the DateTime and remainding minutes when adding or subtracting duration 
-    # to/from a minute in an hour.
-    # Subtraction with a remainder returns the time of the current date as 00:00.
+    # Returns the DateTime and remainding minutes when adding a duration to a minute in the hour. 
+    # A negative duration will subtract the minutes.
+    #
+    # @param [DateTime] time is the full date but only the minute element is used
+    # @param [Integer] duration is the number of minutes to add and can be negative (subtraction)
+    # @param [Boolean] next_hour used in subtraction to specify the starting point as midnight (00:00 the next day)
+    # @return [DateTime,Integer,Boolean] The <tt>DateTime</tt> calculated along with remaining minutes and a flag indicating if starting point is next hour
     #
     def calc(time,duration,next_hour=false)
     
@@ -67,8 +83,10 @@ module Workpattern
       end 
     end
     
-    # :call-seq: diff(start,finish) => Integer
-    # returns the number of minutes between two minutes
+    # Returns the number of minutes between two minutes
+    # @param [Integer] start first minute in range
+    # @param [Integer] finish last minute in range
+    # @return [Integer] number of working minutes in the range
     #
     def diff(start,finish)
       start,finish=finish,start if start > finish
@@ -78,22 +96,39 @@ module Workpattern
     
     private
 
-    # sets working pattern
+    # Sets a working pattern
+    #
+    # @param [Integer] start is first minute in the range
+    # @param [Integer] finish is last minute in the range
+    #
     def working(start,finish)
       return self | mask(start,finish)
     end
     
-    # sets resting pattern
+    # sets a resting pattern
+    #
+    # @param [Integer] start is first minute in the range
+    # @param [Integer] finish is last minute in the range
+    #
     def resting(start,finish)
       return self & ((2**60-1)-mask(start,finish))
     end
     
-    # creates a mask over the specified bits
+    # Creates a bit mask of 1's over the specified range
+    #
+    # @param [Integer] start is first minute in the range
+    # @param [Integer] finish is the last minute in the range
+    #
     def mask(start,finish)
       return ((2**(finish+1)-1)-(2**start-1))
     end
     
-    # adds a duration to a time
+    # Handles the addition of minutes to a time
+    #
+    # @param [DateTime] time is the full date but only the minute element is used
+    # @param [Integer] duration is the number of minutes to add and can be negative (subtraction)
+    # @return [DateTime, Integer] The resulting DateTime and any remaining minutes
+    #
     def add(time,duration)
       start = time.min
       available_minutes=minutes(start,59)
@@ -121,7 +156,12 @@ module Workpattern
       return result_date, result_remainder  
     end
     
-    # subtracts a duration from a time
+    # Handles the subtraction of minutes from a time.
+    # @param [DateTime] time is the full date but only the minute element is used
+    # @param [Integer] duration is the number of minutes to add and can be negative (subtraction)
+    # @param [Boolean] next_hour indicates if the 59th second is the first one to be included
+    # @return [DateTime, Integer] The resulting DateTime and any remaining minutes
+    #
     def subtract(time,duration,next_hour)
       if next_hour
         if working?(59)
@@ -157,10 +197,9 @@ module Workpattern
   end
 end
 
-class Fixnum
+# Hours are represented by a bitwise <tt>Integer</tt> class so the code is mixed in to that class
+# @ since 0.3.0
+#
+class Integer
   include Workpattern::Hour
 end
-class Bignum
-  include Workpattern::Hour
-end
-  

data/lib/workpattern/utility/base.rb

@@ -1,11 +1,29 @@
 module Workpattern
-  
+
+  # Mixins expected to be used in more than one class
+  #
+  # @since 0.2.0
+  #
   module Utility
-  
+
+    # Returns the supplied <tt>DateTime</tt> at the very start of the day.
+    #
+    # @param [DateTime] adate is the <tt>DateTime</tt> to be changed
+    # @return [DateTime] 
+    # 
+    # @todo Consider mixin for DateTime class 
+    #
     def midnight_before(adate)
       return adate -(HOUR * adate.hour) - (MINUTE * adate.min)
     end
     
+    # Returns the supplied <tt>DateTime</tt> at the very start of the next day.
+    #
+    # @param [DateTime] adate is the <tt>DateTime</tt> to be changed
+    # @return [DateTime] 
+    # 
+    # @todo Consider mixin for DateTime class  
+    #
     def midnight_after(adate)
       return midnight_before(adate.next_day)
     end

data/lib/workpattern/version.rb

@@ -1,3 +1,5 @@
 module Workpattern
-  VERSION = '0.3.0'
+  # Version Number for Workpattern gem
+  # @since 0.0.1
+  VERSION = '0.3.1'
 end  

data/lib/workpattern/week.rb

@@ -4,26 +4,29 @@ module Workpattern
   # @!attribute values
   #   @return [Array] each day of the week
   # @!attribute days
-  #   @return [Fixnum] number of days in the week
+  #   @return [Integer] number of days in the week
   # @!attribute start
   #   @return [DateTime] first date in the range
   # @!attribute finish
   #   @return [DateTime] last date in the range
   # @!attribute week_total
-  #   @return [Fixnum] total number of minutes in a week
+  #   @return [Integer] total number of minutes in a week
   # @!attribute total
-  #   @return [Fixnum] total number of minutes in the range
+  #   @return [Integer] total number of minutes in the range
   #  
   # Represents working and resting periods for each day in a week for a specified date range.
   #
+  # @since 0.2.0
+  #
   class Week
     
     attr_accessor :values, :days, :start, :finish, :week_total, :total
 
-    # Initialises an instance of class Week
+    # The new <tt>Week</tt> object can be created as either working or resting.
+    #
     # @param [DateTime] start first date in the range
     # @param [DateTime] finish last date in the range
-    # @param [Fixnum] type working (1) or resting (0)
+    # @param [Integer] type working (1) or resting (0)
     # @return [Week] newly initialised Week object    
     #
     def initialize(start,finish,type=1)
@@ -36,8 +39,9 @@ module Workpattern
       set_attributes
     end
     
-    # Duplicates the current Week object
-    # @return [Week] a duplicated instance of the current Week object
+    # Duplicates the current <tt>Week</tt> object
+    #
+    # @return [Week] a duplicated instance of the current <tt>Week</tt> object
     #
     def duplicate()
       duplicate_week=Week.new(@start,@finish)
@@ -55,15 +59,18 @@ module Workpattern
       return duplicate_week
     end
     
-    # Recalculates the attributes that defines a Week object.
-    # This was made public for #duplicate to work
+    # Recalculates the attributes that define a <tt>Week</tt> object.
+    # This was made public for <tt>#duplicate</tt> to work
     #
     def refresh
       set_attributes
     end
     
     # Changes the date range.
-    # This method calls #refresh to update the attributes.
+    # This method calls <tt>#refresh</tt> to update the attributes.
+    #
+    # @param [DateTime] start is the new starting date for the <tt>Week</tt>
+    # @param [DateTime] finish is the new finish date for the <tt>Week</tt>    
     #
     def adjust(start,finish)
       @start=DateTime.new(start.year,start.month,start.day)
@@ -73,18 +80,21 @@ module Workpattern
     
     # Sets a range of minutes in a week to be working or resting.  The parameters supplied
     # to this method determine exactly what should be changed
-    # @param [Hash] days identifies the days to be included in the range
+    #
+    # @param [Hash(DAYNAMES)] days identifies the days to be included in the range
     # @param [DateTime] from_time where the time portion is used to specify the first minute to be set
     # @param [DateTime] to_time where the time portion is used to specify the last minute to be set
-    # @param [Fixnum] type where a 1 sets it to working and a 0 to resting
+    # @param [Integer] type where a 1 sets it to working and a 0 to resting
+    #
     def workpattern(days,from_time,to_time,type)
       DAYNAMES[days].each {|day| @values[day].workpattern(from_time,to_time,type)}  
       refresh
     end
     
     # Calculates a new date by adding or subtracting a duration in minutes.
+    #
     # @param [DateTime] start original date
-    # @param [Fixnum] duration minutes to add or subtract
+    # @param [Integer] duration minutes to add or subtract
     # @param [Boolean] midnight flag used for subtraction that indicates the start date is midnight
     #
     def calc(start,duration, midnight=false)
@@ -94,13 +104,14 @@ module Workpattern
       return subtract(start,duration, midnight) if duration <0  
     end
     
-    # Comparison — Returns an integer (-1, 0, or +1) if week is less than, equal to, or greater than other_week
+    # Comparison Returns an integer (-1, 0, or +1) if week is less than, equal to, or greater than other_week
+    #
     # @param [Week] other_week object to compare to
     # @return [Integer] -1,0 or +1 if week is less than, equal to or greater than other_week
-    def <=>(obj)
-      if @start < obj.start
+    def <=>(other_week)
+      if @start < other_week.start
         return -1
-      elsif @start == obj.start
+      elsif @start == other_week.start
         return 0
       else
         return 1
@@ -108,6 +119,7 @@ module Workpattern
     end
     
     # Returns true if the supplied DateTime is working and false if resting
+    #
     # @param [DateTime] start DateTime to be tested
     # @return [Boolean] true if the minute is working otherwise false if it is a resting minute
     #
@@ -116,10 +128,10 @@ module Workpattern
     end    
 
     # Returns the difference in minutes between two DateTime values.
+    #
     # @param [DateTime] start starting DateTime
     # @param [DateTime] finish ending DateTime
-    # @return [Fixnum] number of minutes
-    # @return [DateTime] start date for rest of calculation.  The calculation is complete when this is the same as the finish date
+    # @return [Integer, DateTime] number of minutes and start date for rest of calculation.
     #
     def diff(start,finish)
       start,finish=finish,start if ((start <=> finish))==1
@@ -159,9 +171,10 @@ module Workpattern
     end
     
     # Calculates the total number of minutes between two dates
+    #
     # @param [DateTime] start is the first date in the range
     # @param [DateTime] finish is the last date in the range
-    # @return [Fixnum] total number of minutes between supplied dates
+    # @return [Integer] total number of minutes between supplied dates
     #
     def total_hours(start,finish)
       total=0
@@ -171,13 +184,13 @@ module Workpattern
       return total
     end
     
-    # Adds a duration in minutes to a date
+    # Adds a duration in minutes to a date.
+    #
+    # The Boolean returned is always false.
+    #
     # @param [DateTime] start original date
-    # @param [Fixnum] duration minutes to add
-    # @param [Boolean] midnight flag used for subtraction that indicates the start date is midnight
-    # @return [DateTime] the calculated date
-    # @return [Fixnum] the number of minutes still to be added
-    # @return [Boolean] Always false, this is the flag used for subtraction
+    # @param [Integer] duration minutes to add
+    # @return [DateTime, Integer, Boolean] the calculated date, remaining minutes and flag used for subtraction
     #
     def add(start,duration)
       # aim to calculate to the end of the day
@@ -220,12 +233,12 @@ module Workpattern
     end
     
     # Subtracts a duration in minutes from a date
+    #
     # @param [DateTime] start original date
-    # @param [Fixnum] duration minutes to subtract - always a negative
+    # @param [Integer] duration minutes to subtract - always a negative
     # @param [Boolean] midnight flag indicates the start date is midnight when true
-    # @return [DateTime] the calculated date
-    # @return [Fixnum] the number of minutes still to be subtracted
-    # @return [Boolean] When set to true indicates the time is midnight on the given date
+    # @return [DateTime, Integer, Boolean] the calculated date, remaining number of minutes and 
+    #     true if the time is midnight on the date
     #
     def subtract(start,duration,midnight=false)
       
@@ -286,10 +299,11 @@ module Workpattern
     
     # Supports calculating from midnight by updating the given duration depending on whether the
     # last minute in the day is resting or working.  It then sets the time to this minute.
+    #
     # @param [DateTime] start is the date whose midnight is to be used as the start date
-    # @param [Fixnum] duration is the number of minutes to subtract
-    # @return [DateTime] the date with a time of 23:59
-    # @return [Fixnum] the duration adjusted according to whether 23:59 is resting or not
+    # @param [Integer] duration is the number of minutes to subtract
+    # @return [DateTime, Integer] the date with a time of 23:59 and remaining duration
+    #     adjusted according to whether 23:59 is resting or not
     #
     def minute_b4_midnight(start,duration)
       start -= start.hour * HOUR
@@ -300,6 +314,7 @@ module Workpattern
     end  
     
     # Calculates the date and time after the last working minute of the current date
+    #
     # @param [DateTime] start is the current date
     # @return [DateTime] the new date
     #
@@ -314,11 +329,11 @@ module Workpattern
     end
     
     # Calculates the difference between two dates that exist in this Week object.
+    #
     # @param [DateTime] start first date 
     # @param [DateTime] finish last date
     # @param [DateTime] finish_on the range to be used in this Week object.  
-    # @return [DateTime] new date for rest of calculation otherwise same as finish if completed calculation
-    # @return [Fixnum] total number of minutes calculated thus far.
+    # @return [DateTime, Integer] new date for rest of calculation and total number of minutes calculated thus far.
     #
     def diff_detail(start,finish,finish_on)
       duration, start=@values[start.wday].diff(start,finish)