useful_utilities 5.4.5 → 5.4.6

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: e5e4bbec43984ce6756ade1190a5f21e4dfbaf5e
-  data.tar.gz: 236d91abef2bedcfaaab5e49c7c78cc998a5eedd
+  metadata.gz: 79bd418ad8787d74738d6fd2b99030e6c698ee1c
+  data.tar.gz: 1f227b9d219366903e323a70b043bf951eb12f6a
 SHA512:
-  metadata.gz: 79972ec7576ea4d937a16a113cdf10082c7bad7a0b415b46a6adf56ead972caf76c3edc17286e6640c84b726fc48884726ba276c9647f20358b97b04a4cc94d7
-  data.tar.gz: 35b254e47c6638587ae79491a8eb013cbc39ea5fd5503a668f7847588eee3a8d2af74d32538e7fd52a0bb9f21236b0daf5048f73d4480ac74a4fdc1c92a58cb2
+  metadata.gz: f09b24ef2b0714e6d53638984f206f04a89335fbdc37df399ae65ee66307b2094684629c0ded231edbd46947a705fcd4a0d3931ee9071a5943e1931c29069905
+  data.tar.gz: 490c74b2afb5ac686e72f145739a29e8af0a5fc6dce80fb38985a3e4880cb8b5b65bcffa3def2626e1be001ed190ab44550b09a7aff3a3ae72a7c2ef378b94d2

data/lib/useful_utilities/api.rb

@@ -2,16 +2,25 @@ require 'socket'
 require 'timeout'
 
 module UsefulUtilities
+  # API utilities
   module Api
     extend self
 
+    # @note Exceptions to handle
+    # @see #port_open?
     RESCUE_PORT_OPEN_EXCEPTIONS = [Errno::ENETUNREACH, Errno::ECONNREFUSED, Errno::EHOSTUNREACH, SocketError, Timeout::Error].freeze
 
+    # @param value [Numeric]
+    # @return [FalseClass/Numeric] false if value is infinity or value if not
     def convert_limit(value)
       value == Float::INFINITY ? false : value
     end
 
-    # checks if a port is open or not on a remote host
+    # @param ip [String]
+    # @param port [Integer]
+    # @option sleep_time [Integer] :sleep_time (1)
+    # @option max_attempts [Integer] :max_attempts (3)
+    # @return [Boolean] check if a port is open or not on a remote host
     def port_open?(ip, port, sleep_time: 1, max_attempts: 3)
       try_to(max_attempts: max_attempts, sleep_time: sleep_time, rescue_what: RESCUE_PORT_OPEN_EXCEPTIONS) do
         Timeout::timeout(sleep_time) do

data/lib/useful_utilities/ar.rb

@@ -2,8 +2,14 @@ require 'active_record'
 require 'active_support/all'
 
 module UsefulUtilities
+  # ActiveRecord utilities
   module AR
+
+    # Includable AR extension
+    # To use it include this module to your model
     module Methods
+      # @param association_class [Class]
+      # @return [String] foreign key
       def foreign_key(association_class)
         reflections.values.find do |reflection|
           reflection.class_name == association_class.name
@@ -18,6 +24,8 @@ module UsefulUtilities
     TYPE_SUFFIX = '%s_type'
     ID_SUFFIX = '%s_id'
 
+    # @param value
+    # @return [Integer] value as Integer
     def value_to_integer(value)
       return 0 if value.nil?
       return 0 if value == false
@@ -26,27 +34,41 @@ module UsefulUtilities
       ActiveRecord::Type::Integer.new.type_cast_from_database(value)
     end
 
+    # @param value
+    # @return [BigDecimal] value as BigDecimal
     def value_to_decimal(value)
       return BigDecimal.new(0) if value.nil?
 
       ActiveRecord::Type::Decimal.new.type_cast_from_database(value)
     end
 
+    # @param value
+    # @return [Boolean] value as boolean
     def value_to_boolean(value)
       return false if value.nil?
 
       ActiveRecord::Type::Boolean.new.type_cast_from_database(value)
     end
 
+    # @param value
+    # @return [Float] value as float
+    # @example
+    #   UsefulUtilities::AR.boolean_to_float(false) #=> 0.0
+    #   UsefulUtilities::AR.boolean_to_float(true)  #=> 1.0
     def boolean_to_float(value)
       value ? 1.0 : 0.0
     end
 
+    # @param record
+    # Validates record and associations
     def deep_validation(record)
       record.valid?
       nested_associations_validation(record)
     end
 
+    # @param record
+    # @param nested [Boolean]
+    # Validates nested associations of a record
     def nested_associations_validation(record, nested = false)
       record.class.reflections.each do |name, reflection|
         next unless NESTED_ASSOCIATIONS.include?(reflection.macro)
@@ -63,12 +85,19 @@ module UsefulUtilities
       end
     end
 
+    # @param scope [ActiveRecord::Relation]
+    # @param key [Symbol]
+    # @param value value to search
+    # @return [ActiveRecord::Relation]
     def by_polymorphic(scope, key, value)
       type = to_polymorphic_type(value)
       type_column, id_column = TYPE_SUFFIX % key, ID_SUFFIX % key
       scope.where(type_column => type, id_column => value)
     end
 
+    # @param value
+    # @return value if value does not respond to base_class
+    # @return [Class] base class
     def to_polymorphic_type(value)
       klass =
         if value.is_a?(Class) || value.nil? then value
@@ -79,23 +108,37 @@ module UsefulUtilities
       klass.respond_to?(:base_class) ? klass.base_class : klass
     end
 
+    # @param klass [Class]
+    # @param columns list of columns
+    # @return [String] qualified columns splitted by comma
     def [](klass, *columns)
       columns.map { |column| "#{ klass.table_name }.#{ column }" }.join(', ')
     end
 
+    # @param klass [Class]
+    # @param column [String/Symbol]
+    # @return [String] ASC statement for ORDER BY
     def asc(klass, column)
       "#{ self[klass, column] } ASC"
     end
 
+    # @param klass [Class]
+    # @param column [String/Symbol]
+    # @return [String] DESC statement for ORDER BY
     def desc(klass, column)
       "#{ self[klass, column] } DESC"
     end
 
+    # @param scope [ActiveRecord::Relation]
+    # @param _value class or column
+    # @return [ActiveRecord::Relation]
     def older_than(scope, _value)
       value = _value.is_a?(ActiveRecord::Base) ? _value.id : _value
       value.present? ? scope.where("#{ self[scope, :id] } < ?", value) : scope
     end
 
+    # @param args list of columns
+    # @return COALESCE statement
     def null_to_zero(*args)
       sql_column =
         case args.size
@@ -108,14 +151,21 @@ module UsefulUtilities
       "COALESCE(#{ sql_column }, 0)"
     end
 
+    # @param value
+    # @return CEILING statement
     def ceil(value)
       "CEILING(#{value})"
     end
 
+    # @param args
+    # @param result alias
+    # @return SUM statement
     def sql_sum(*args, result)
       "SUM(#{ null_to_zero(*args) }) AS #{ result }"
     end
 
+    # @param scope [ActiveRecord::Relation]
+    # @param all_columns list of columns
     # Can be used for not NULL columns only
     # sum_by_columns(Virtual, :column_1, :column2, column3: :column3_alias...)
     def sum_by_columns(scope, *all_columns)
@@ -123,16 +173,29 @@ module UsefulUtilities
       columns_with_aliases = columns.extract_options!
 
       sql_query =
-        columns.reduce(columns_with_aliases) { |res, column| res.merge!(column => column) }.
-                map { |column, column_alias| "SUM(#{ column }) AS #{ column_alias }" }.join(', ')
+        columns.reduce(columns_with_aliases) do |res, column|
+          res.merge!(column => column)
+        end.
+        map do |column, column_alias|
+          "COALESCE(SUM(#{ column }), 0) AS #{ column_alias }"
+        end.
+        join(', ')
 
       scope.select(sql_query).first
     end
 
-    def count(table, column, result)
-      "COUNT(#{ self[table, column] }) AS #{ result }"
+    # @param klass [Class]
+    # @param column [String/Symbol]
+    # @param result [String/Symbol] alias
+    # @return [String] count statement
+    def count(klass, column, result)
+      "COUNT(#{ self[klass, column] }) AS #{ result }"
     end
 
+    # @param owner
+    # @param self_class [Class]
+    # @param dependent_class [Class]
+    # Deletes dependent records
     def delete_dependents(owner, self_class, dependent_class)
       dependent_fk = dependent_class.foreign_key(self_class)
       self_fk = self_class.foreign_key(owner.class)

data/lib/useful_utilities/centos_version.rb

@@ -1,4 +1,5 @@
 module UsefulUtilities
+  # CentOS versions utilities
   class CentOSVersion
     attr_reader :version
 

data/lib/useful_utilities/hash.rb

@@ -1,4 +1,5 @@
 module UsefulUtilities
+  # Hash utilities
   module Hash
     extend self
 

data/lib/useful_utilities/i18n.rb

@@ -1,7 +1,10 @@
 module UsefulUtilities
+  # I18n utilities
   module I18n
     extend self
 
+    # @param object [Object]
+    # @return [String] humanized name
     def humanize_type(object)
       klass = case object
               when Class then object

data/lib/useful_utilities/numeric.rb

@@ -1,4 +1,5 @@
 module UsefulUtilities
+  # Numeric utilities
   module Numeric
     extend self
 
@@ -7,21 +8,33 @@ module UsefulUtilities
     MILLION = 1_000_000
     BILLION = 1_000_000_000
 
+    # @param value [Numeric]
+    # @return [Numeric]
+    # @example
+    #   UsefulUtilities::Numeric.positive_or_zero(1)  #=> 1
+    #   UsefulUtilities::Numeric.positive_or_zero(-1) #=> 0
     def positive_or_zero(value)
       (value > ZERO) ? value : ZERO
     end
 
+    # @param value [Numeric]
+    # @return [Numeric] value if value can not be coerced to integer
     def float_or_integer(value)
       value == value.to_i ? value.to_i : value
     end
 
+    # @param value [Numeric]
+    # @option scale [Integer] :scale (nil)
+    # @return [BigDecimal] value as BigDecimale rounded to scale
     def to_decimal(value, scale: nil)
       result = value.to_f.to_d
 
       scale ? result.round(scale) : result
     end
 
-    # @note: used SI metric prefixes http://en.wikipedia.org/wiki/SI_prefix
+    # @param value [Numeric]
+    # @param unit [Symbol]
+    # @return [Numeric] value converted to kilo
     def to_kilo(value, unit)
       if    unit == :M then value * THOUSAND
       elsif unit == :G then value * MILLION
@@ -29,6 +42,9 @@ module UsefulUtilities
       end
     end
 
+    # @param value [Numeric]
+    # @param unit [Symbol]
+    # @return [Numeric] value converted to giga
     def to_giga(value, unit)
       if    unit == :k then value.fdiv(MILLION)
       elsif unit == :M then value.fdiv(THOUSAND)
@@ -36,6 +52,10 @@ module UsefulUtilities
       end
     end
 
+
+    # @param value [Numeric]
+    # @param unit [Symbol]
+    # @return [Numeric] value converted to number
     def to_number(value, unit)
       if    unit == :M then value * MILLION
       elsif unit == :G then value * BILLION

data/lib/useful_utilities/redhat_release.rb

@@ -1,4 +1,5 @@
 module UsefulUtilities
+  # Redhat releases utilities
   class RedhatRelease
     LEGACY_DISTRO_TEMPLATE = 'centos%{major_version}'.freeze
 

data/lib/useful_utilities/size/bit.rb

@@ -2,35 +2,57 @@ require_relative 'standard/decimal'
 
 module UsefulUtilities
   module Size
+    # Possible units:
+    #   :bit  - bits
+    #   :kbit - kilobits
+    #   :Mbit - megabits
+    #   :Gbit - gigabits
+    #   :Tbit - terabits
+    # Used SI standard http://en.wikipedia.org/wiki/Binary_prefix
+    #   Decimal
+    #   1 K = 1000
     module Bit
-      # @note: used SI standard http://en.wikipedia.org/wiki/Binary_prefix
-      #   Decimal
-      #   1 K = 1000
       include UsefulUtilities::Size::Standard::Decimal
 
+      # @param size [Numeric]
+      # @param unit [Symbol]
+      # @return [Numeric] size in terabits
       def to_terabits(size, unit)
         to_tera(size, bit_prefix(unit))
       end
 
+      # @param size [Numeric]
+      # @param unit [Symbol]
+      # @return [Numeric] size in gigabits
       def to_gigabits(size, unit)
         to_giga(size, bit_prefix(unit))
       end
 
+      # @param size [Numeric]
+      # @param unit [Symbol]
+      # @return [Numeric] size in megabits
       def to_megabits(size, unit)
         to_mega(size, bit_prefix(unit))
       end
 
+      # @param size [Numeric]
+      # @param unit [Symbol]
+      # @return [Numeric] size in kilobits
       def to_kilobits(size, unit)
         to_kilo(size, bit_prefix(unit))
       end
 
+      # @param size [Numeric]
+      # @param unit [Symbol]
+      # @return [Numeric] size in bits
       def to_bits(size, unit)
         to_decimal_bi(size, bit_prefix(unit))
       end
 
-      # Convert bits to manually defined format
-      #   by using parameter 'unit'
-      #   ATTENTION: by default round is eq to 3 digits
+      # @param size [Numeric]
+      # @param unit [Symbol]
+      # @param rounder [Integer]
+      # @return [Numeric] humanized size in provided unit
       def bits_to_human_size(size, unit, rounder = 3)
         case unit
         when :bit  then size.round(rounder)
@@ -42,8 +64,9 @@ module UsefulUtilities
         end
       end
 
-      # Ignore any fractional part of the number
-      #   Bit can be only integer !!!
+      # @param value [Integer]
+      # @return [Symbol] suitable unit
+      # @raise [ArgumentError] if value is not integer or less than zero
       def suitable_unit_for_bits(value)
         return not_integer!(value)          unless value.is_a?(Integer)
         return not_positive_integer!(value) unless value > -1
@@ -56,6 +79,8 @@ module UsefulUtilities
         end
       end
 
+      # @param value_in_bits [Integer] value in bits
+      # @return [String] human readable value
       def bits_per_sec_to_human_readable(value_in_bits)
         unit  = suitable_unit_for_bits(value_in_bits)
         value = bits_to_human_size(value_in_bits, unit.to_sym)

data/lib/useful_utilities/size/byte.rb

@@ -2,26 +2,44 @@ require_relative 'standard/binary'
 
 module UsefulUtilities
   module Size
+    # Possible units:
+    #   :B  - bytes
+    #   :KB - kilobytes
+    #   :MB - megabytes
+    #   :GB - gigabytes
+    #   :TB - terabytes
+    # Used ISO standard http://en.wikipedia.org/wiki/Binary_prefix
+    #   Binary
+    #   1 K = 1024
     module Byte
-      # @note: used ISO standard http://en.wikipedia.org/wiki/Binary_prefix
-      #   Binary
-      #   1 K = 1024
       include UsefulUtilities::Size::Standard::Binary
 
       HALF_OF_SECTOR = 0.5
 
+      # @param size [Numeric]
+      # @param unit [Symbol]
+      # @return [Numeric] size in terabytes
       def to_terabytes(size, unit)
         to_tebi(size, byte_prefix(unit))
       end
 
+      # @param size [Numeric]
+      # @param unit [Symbol]
+      # @return [Numeric] size in gigabytes
       def to_gigabytes(size, unit)
         to_gibi(size, byte_prefix(unit))
       end
 
+      # @param size [Numeric]
+      # @param unit [Symbol]
+      # @return [Numeric] size in megabytes
       def to_megabytes(size, unit)
         to_mebi(size, byte_prefix(unit))
       end
 
+      # @param size [Numeric]
+      # @param unit [Symbol]
+      # @return [Numeric] size in kilobytes
       def to_kilobytes(size, unit)
         if unit == :sector
           return (size * HALF_OF_SECTOR).round # http://en.wikipedia.org/wiki/Disk_sector
@@ -30,13 +48,17 @@ module UsefulUtilities
         to_kibi(size, byte_prefix(unit))
       end
 
+      # @param size [Numeric]
+      # @param unit [Symbol]
+      # @return [Numeric] size in bytes
       def to_bytes(size, unit)
         to_binary_bi(size, byte_prefix(unit))
       end
 
-      # Convert bytes to manually defined format
-      #   by using parameter 'unit'
-      #   ATTENTION: by default round is eq to 3 digits
+      # @param size [Numeric]
+      # @param unit [Symbol]
+      # @param rounder [Integer]
+      # @return [Numeric] humanized size in provided unit
       def bytes_to_human_size(size, unit, rounder = 3)
         case unit
         when :B  then size.round(rounder)

data/lib/useful_utilities/size/cdn_speed.rb

@@ -2,12 +2,21 @@ require_relative 'standard/decimal'
 
 module UsefulUtilities
   module Size
+    # Possible units:
+    #   :bit  - bits
+    #   :kbit - kilobits
+    #   :Mbit - megabits
+    #   :Gbit - gigabits
+    #   :Tbit - terabits
+    # Used SI standard http://en.wikipedia.org/wiki/Binary_prefix
+    #   Decimal
+    #   1 K = 1000
     module CdnSpeed
-      # @note: used SI standard http://en.wikipedia.org/wiki/Binary_prefix
-      #   Decimal
-      #   1 K = 1000
       include UsefulUtilities::Size::Standard::Decimal
 
+      # @param speed [Numeric]
+      # @param unit [Symbol]
+      # @return [Numeric] size in CDN gigabits per second
       def to_cdn_gbps(speed, unit)
         to_giga(speed, bit_prefix(unit))/8
       end

data/lib/useful_utilities/size/frequency.rb

@@ -2,16 +2,29 @@ require_relative 'standard/decimal'
 
 module UsefulUtilities
   module Size
+    # Frequency utilities
+    # Possible units:
+    #   :Hz  - hertz
+    #   :KHz - kilohertz
+    #   :MHz - megahertz
+    #   :GHz - gigahertz
+    #   :THz - terahertz
+    # Used SI standard http://en.wikipedia.org/wiki/Binary_prefix
+    #   Decimal
+    #   1 K = 1000
     module Frequency
-      # @note: used SI standard http://en.wikipedia.org/wiki/Binary_prefix
-      #   Decimal
-      #   1 K = 1000
       include UsefulUtilities::Size::Standard::Decimal
 
+      # @param size [Numeric]
+      # @param unit [Symbol]
+      # @return [Numeric] size in megahertz
       def to_megahertz(size, unit)
         to_mega(size, frequency_prefix(unit))
       end
 
+      # @param size [Numeric]
+      # @param unit [Symbol]
+      # @return [Numeric] size in gigahertz
       def to_gigahertz(size, unit)
         to_giga(size, frequency_prefix(unit))
       end

data/lib/useful_utilities/size/percentage.rb

@@ -1,12 +1,17 @@
 module UsefulUtilities
   module Size
+    # Percentage utilities
     module Percentage
       HUNDRED = 100
 
+      # @param fraction [Numeric]
+      # @return [Numeric] fraction converted to percentage
       def fraction_to_percentage(fraction)
         fraction * HUNDRED
       end
 
+      # @param percentage [Numeric]
+      # @return [Float] percentage converted to fraction
       def percentage_to_fraction(percentage)
         percentage.fdiv(HUNDRED)
       end

data/lib/useful_utilities/size/standard/binary.rb

@@ -1,14 +1,23 @@
 module UsefulUtilities
   module Size
     module Standard
+      # Possible prefixes:
+      #   :B   - bytes
+      #   :KiB - kibibytes
+      #   :MiB - mebibytes
+      #   :GiB - gibibytes
+      #   :TiB - tebibytes
+      # Used ISO standard http://en.wikipedia.org/wiki/Binary_prefix
       module Binary
-        # @note: used ISO standard http://en.wikipedia.org/wiki/Binary_prefix
 
         KIBI = 1024      # KiB
         MEBI = KIBI ** 2 # MiB
         GIBI = KIBI ** 3 # GiB
         TEBI = KIBI ** 4 # TiB
 
+        # @param val [Numeric]
+        # @param prefix [Symbol]
+        # @return [Numeric] val in tebibytes
         def to_tebi(val, prefix)
           case prefix
           when :B   then val.fdiv(TEBI)
@@ -20,6 +29,9 @@ module UsefulUtilities
           end
         end
 
+        # @param val [Numeric]
+        # @param prefix [Symbol]
+        # @return [Numeric] val in gibibytes
         def to_gibi(val, prefix)
           case prefix
           when :B   then val.fdiv(GIBI)
@@ -31,6 +43,9 @@ module UsefulUtilities
           end
         end
 
+        # @param val [Numeric]
+        # @param prefix [Symbol]
+        # @return [Numeric] val in mebibytes
         def to_mebi(val, prefix)
           case prefix
           when :B   then val.fdiv(MEBI)
@@ -42,6 +57,9 @@ module UsefulUtilities
           end
         end
 
+        # @param val [Numeric]
+        # @param prefix [Symbol]
+        # @return [Numeric] val in kibibytes
         def to_kibi(val, prefix)
           case prefix
           when :B   then val.fdiv(KIBI)
@@ -53,6 +71,9 @@ module UsefulUtilities
           end
         end
 
+        # @param val [Numeric]
+        # @param prefix [Symbol]
+        # @return [Numeric] val in bytes
         def to_binary_bi(val, prefix)
           case prefix
           when :B   then val

data/lib/useful_utilities/size/standard/decimal.rb

@@ -1,8 +1,8 @@
 module UsefulUtilities
   module Size
     module Standard
+      # Used SI standard http://en.wikipedia.org/wiki/Binary_prefix
       module Decimal
-        # @note: used SI standard http://en.wikipedia.org/wiki/Binary_prefix
 
         KILO = 1000      # KB
         MEGA = KILO ** 2 # MB

data/lib/useful_utilities/time.rb

@@ -1,40 +1,66 @@
 require 'active_support/all'
 
 module UsefulUtilities
+  # Utilities for time
+
+  # @author OnApp Ltd.
   module Time
     extend self
 
     SECONDS_IN_HOUR = 3_600
     MILLISECONDS_IN_SECOND = 1_000
 
-    # Whatever time is passed it will return it without any GMT offset and the passed time will be in UTC
-    # t = Time.now              #=> 2013-12-19 14:01:22 +0200
-    # UsefulUtilities::Time.assume_utc(t) #=> 2013-12-19 14:01:22 UTC
+    # @param time [Time]
+    # @return [DateTime] time in UTC
+    # @example
+    #   time #=> 2013-12-19 14:01:22 +0200
+    #
+    #   UsefulUtilities::Time.assume_utc(time) #=> 2013-12-19 14:01:22 UTC
     def assume_utc(time)
       time.to_datetime.change(offset: 0)
     end
 
-    # Examples of usage:
-    # 2014-01-04 14:29:59 #=> 2014-01-04 14:00:00
-    # 2014-01-04 14:30:00 #=> 2014-01-04 15:00:00
+    # @param time [Time]
+    # @return [Time] time rounded to hours
+    # @example
+    #   time #=> 2014-01-04 14:29:59
+    #
+    #   UsefulUtilities::Time.round_to_hours(time) #=> 2014-01-04 14:00:00
     def round_to_hours(time)
       (time.min < 30) ? time.beginning_of_hour : time.end_of_hour
     end
 
+    # @param time [Time]
+    # @return [Time] beginning of the next hour
+    # @example
+    #   time #=> 2018-03-07 15:51:58 +0200
+    #   UsefulUtilities::Time.beginning_of_next_hour(time) #=> 2018-03-07 16:00:00 +0200
     def beginning_of_next_hour(time)
       time.beginning_of_hour.in(1.hour)
     end
 
+    # @param time [Time]
+    # @return [Time] beginning of the next day
+    # @example
+    #   time #=> 2018-03-07 15:51:58 +0200
+    #   UsefulUtilities::Time.beginning_of_next_day(time) #=> 2018-03-08 00:00:00 +0200
     def beginning_of_next_day(time)
       time.beginning_of_day.in(1.day)
     end
 
+    # @param time [Time]
+    # @return [Time] beginning of the next month
+    # @example
+    #   time #=> 2018-03-07 15:51:58 +0200
+    #   UsefulUtilities::Time.beginning_of_next_month(time) #=> 2018-04-01 00:00:00 +0300
     def beginning_of_next_month(time)
       time.beginning_of_month.in(1.month)
     end
 
-    # yields local time of the beginning of each hour
-    # between start time & current time
+    # @param from [Time]
+    # @param till [Time]
+    # Yields local time of the beginning of each hour
+    # between from & till
     def each_hour_from(from, till = ::Time.now)
       cursor = from.dup.utc.beginning_of_hour
       end_time = till.dup.utc.beginning_of_hour
@@ -46,6 +72,10 @@ module UsefulUtilities
       end
     end
 
+    # @param from [Time]
+    # @param till [Time]
+    # Yields local time of the beginning of each day
+    # between from & till
     def each_day_from(from, till = ::Time.now)
       cursor = from.beginning_of_day
       end_time = till.beginning_of_day
@@ -57,9 +87,19 @@ module UsefulUtilities
       end
     end
 
+    # @param time_string [String] string to parse from
+    # @param time_zone [String] timezone
+    # @return [DateTime] parsed time in UTC
+    #
     # Parse and convert Time to the given time zone. If time zone is
     # not given, Time is assumed to be given in UTC. Returns result in
     # UTC
+    #
+    # @example
+    #   time_string #=> "2018-03-07 15:51:58 +0200"
+    #   time_zone   #=> "EET"
+    #
+    #   UsefulUtilities::Time.to_utc(time_string, time_zone) #=> Wed, 07 Mar 2018 13:51:58 +0000
     def to_utc(time_string, time_zone)
       time = ::DateTime.parse(time_string) # Wed, 22 Aug 2012 13:34:18 +0000
     rescue
@@ -74,15 +114,29 @@ module UsefulUtilities
       end
     end
 
+    # @param time [Time]
+    # @return [Integer] time in milliseconds
+    # @example
+    #   time #=> 2018-03-07 15:51:58 +0200
+    #   UsefulUtilities::Time.to_milliseconds(time) #=> 1520430718000
     def to_milliseconds(time)
       time.to_time.to_i * MILLISECONDS_IN_SECOND
     end
 
-    # takes two objects: Time
+    # @param end_time [Time] end time
+    # @param start_time [Time] start time
+    # @return [Integer] difference in hours
+    # @example
+    #   end_time   #=> 2018-03-07 14:51:58 +0200
+    #   start_time #=> 2018-03-07 15:51:58 +0200
+    #
+    #   UsefulUtilities::Time.diff_in_hours(end_time, start_time) #=> 1
     def diff_in_hours(end_time, start_time)
       ((end_time.to_i - start_time.to_i) / SECONDS_IN_HOUR).abs
     end
 
+    # @param date [Date]
+    # @return [Boolean] checks if date is valid
     def valid_date?(date)
       return true if date.acts_like?(:date)
       return false if date.blank?

data/lib/useful_utilities/version.rb

@@ -1,3 +1,3 @@
 module UsefulUtilities
-  VERSION = '5.4.5'.freeze
+  VERSION = '5.4.6'.freeze
 end

data/lib/useful_utilities/yaml.rb

@@ -1,5 +1,5 @@
-# It was used in outdated rake task, but we decided to leave for the future
 module UsefulUtilities
+  # YAML utilities
   module YAML
     extend self
 

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: useful_utilities
 version: !ruby/object:Gem::Version
-  version: 5.4.5
+  version: 5.4.6
 platform: ruby
 authors:
 - OnApp Ltd.
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2018-02-09 00:00:00.000000000 Z
+date: 2018-03-27 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: activesupport
@@ -101,7 +101,6 @@ executables: []
 extensions: []
 extra_rdoc_files: []
 files:
-- README.md
 - Rakefile
 - lib/useful_utilities.rb
 - lib/useful_utilities/api.rb

data/README.md

@@ -1,14 +0,0 @@
-## UsefulUtilities
-
-A collection of useful utilities
-
-This package include next tools with new namespaces:
-
-Api Utilities => UsefulUtilities::Api
-AR Utilities => UsefulUtilities::AR
-Hash Utilities => UsefulUtilities::Hash
-Size Utilities => UsefulUtilities::Size
-Numeric Utilities => UsefulUtilities::Numeric
-Time Utilities => UsefulUtilities::Time
-YAML Utilities => UsefulUtilities::YAML
-I18n Utilities => UsefulUtilities::I18n