Some moar docs

Author: zverok

.yardopts

@@ -0,0 +1,2 @@
+--markup=markdown
+--no-private

lib/time_calc.rb

@@ -196,6 +196,36 @@ def ==(other)
   #     @return [Diff]
   #   @return [Time or Diff]
 
+  # @!method to(date_or_time)
+  #   Produces {Sequence} from this value to `date_or_time`
+  #
+  #   @param date_or_time [Date, Time, DateTime]
+  #   @return [Sequence]
+
+  # @!method step(span, unit = nil)
+  #   Produces endless {Sequence} from this value, with step specified.
+  #
+  #   @overload step(unit)
+  #     Shortcut for `step(1, unit)`
+  #     @param unit [Symbol]
+  #   @overload step(span, unit)
+  #     @example
+  #       TimeCalc.(Time.parse('2019-06-01 14:50')).step(1, :day).take(3)
+  #       # => [2019-06-01 14:50:00 +0300, 2019-06-02 14:50:00 +0300, 2019-06-03 14:50:00 +0300]
+  #     @param span [Integer]
+  #     @param unit [Symbol]
+  #   @return [Sequence]
+
+  # @!method for(span, unit)
+  #   Produces {Sequence} from this value to `this + <span units>`
+  #
+  #   @example
+  #     TimeCalc.(Time.parse('2019-06-01 14:50')).for(2, :weeks).step(1, :day).count
+  #     # => 15
+  #   @param span [Integer]
+  #   @param unit [Symbol]
+  #   @return [Sequence]
+
   # @private
   MATH_OPERATIONS = %i[merge truncate floor ceil round + -].freeze
   # @private

lib/time_calc/diff.rb

@@ -12,6 +12,24 @@ class TimeCalc
   # Allows to easily and correctly calculate number of years/monthes/days/etc between two points in
   # time.
   #
+  # @example
+  #   t1 = Time.parse('2019-06-01 14:50')
+  #   t2 = Time.parse('2019-06-15 12:10')
+  #   (TimeCalc.(t2) - t1).div(:day)
+  #   # => 13
+  #   # the same:
+  #   (TimeCalc.(t2) - t1).days
+  #   # => 13
+  #   (TimeCalc.(t2) - t1).div(3, :hours)
+  #   # => 111
+  #
+  #   (TimeCalc.(t2) - t1).factorize
+  #   # => {:year=>0, :month=>0, :week=>1, :day=>6, :hour=>21, :min=>20, :sec=>0}
+  #   (TimeCalc.(t2) - t1).factorize(weeks: false)
+  #   # => {:year=>0, :month=>0, :day=>13, :hour=>21, :min=>20, :sec=>0}
+  #   (TimeCalc.(t2) - t1).factorize(weeks: false, zeroes: false)
+  #   # => {:day=>13, :hour=>21, :min=>20, :sec=>0}
+  #
   class Diff
     # @private
     attr_reader :from, :to
@@ -80,6 +98,28 @@ def div(span, unit = nil)
       singular_div(unit).div(span)
     end
 
+    # @!method years
+    #   Whole years in diff.
+    #   @return [Integer]
+    # @!method months
+    #   Whole months in diff.
+    #   @return [Integer]
+    # @!method weeks
+    #   Whole weeks in diff.
+    #   @return [Integer]
+    # @!method days
+    #   Whole days in diff.
+    #   @return [Integer]
+    # @!method hours
+    #   Whole hours in diff.
+    #   @return [Integer]
+    # @!method minutes
+    #   Whole minutes in diff.
+    #   @return [Integer]
+    # @!method seconds
+    #   Whole seconds in diff.
+    #   @return [Integer]
+
     # Same as integer modulo: the "rest" of whole division of the distance between two time points by
     # `<span> <units>`. This rest will be also time point, equal to `first diff operand - span units`
     #

lib/time_calc/op.rb

@@ -25,10 +25,31 @@ def inspect
       '<%s %s>' % [self.class, @chain.map { |name, *args| "#{name}(#{args.join(' ')})" }.join('.')]
     end
 
-    TimeCalc::OPERATIONS.each do |name|
+    TimeCalc::MATH_OPERATIONS.each do |name|
       define_method(name) { |*args| Op.new([*@chain, [name, *args]]) }
     end
 
+    # @!method +(span, unit)
+    #   Adds `+(span, unit)` to method chain
+    #   @see TimeCalc#+
+    #   @return [Op]
+    # @!method -(span, unit)
+    #   Adds `-(span, unit)` to method chain
+    #   @see TimeCalc#-
+    #   @return [Op]
+    # @!method floor(unit)
+    #   Adds `floor(span, unit)` to method chain
+    #   @see TimeCalc#floor
+    #   @return [Op]
+    # @!method ceil(unit)
+    #   Adds `ceil(span, unit)` to method chain
+    #   @see TimeCalc#ceil
+    #   @return [Op]
+    # @!method round(unit)
+    #   Adds `round(span, unit)` to method chain
+    #   @see TimeCalc#round
+    #   @return [Op]
+
     # Performs the whole chain of operation on parameter, returning the result.
     #
     # @param date_or_time [Date, Time, DateTime]

lib/time_calc/version.rb

@@ -0,0 +1,6 @@
+# frozen_string_literal: true
+
+class TimeCalc
+  # @private
+  VERSION = '0.1.1'
+end

time_calc.gemspec

@@ -0,0 +1,38 @@
+require './lib/time_calc/version'
+
+Gem::Specification.new do |s|
+  s.name     = 'time_calc'
+  s.version  = TimeCalc::VERSION
+  s.authors  = ['Victor Shepelev']
+  s.email    = '[email protected]'
+  s.homepage = 'https://github.com/zverok/time_calc'
+
+  s.summary = 'Easy time math'
+  s.description = <<-EOF
+    TimeCalc is a library for idiomatic time calculations, like "plus N days", "floor to month start",
+    "how many hours between those dates", "sequence of months from this to that". It intends to
+    be small and easy to remember without any patching of core classes.
+  EOF
+  s.licenses = ['MIT']
+
+  s.required_ruby_version = '>= 2.3.0'
+
+  s.files = `git ls-files lib LICENSE.txt *.md`.split($RS)
+  s.require_paths = ["lib"]
+
+  s.add_runtime_dependency 'backports', '>= 3.15.0'
+
+  s.add_development_dependency 'rubocop', '~> 0.72.0'
+  s.add_development_dependency 'rubocop-rspec', '>= 1.17.1'
+
+  s.add_development_dependency 'rspec', '>= 3.8'
+  s.add_development_dependency 'rspec-its', '~> 1'
+  s.add_development_dependency 'saharspec'
+  s.add_development_dependency 'simplecov', '~> 0.9'
+  s.add_development_dependency 'tzinfo'
+
+  s.add_development_dependency 'rake'
+  s.add_development_dependency 'rubygems-tasks'
+
+  s.add_development_dependency 'yard'
+end