tins 1.43.0 → 1.44.1

data/lib/tins/concern.rb

@@ -1,9 +1,49 @@
 module Tins
+  # A module concern implementation that supports dependency tracking, class
+  # method inclusion, and block execution hooks.
+  #
+  # This module provides a way to define reusable module functionality with
+  # automatic dependency management, class method injection, and lifecycle
+  # callbacks similar to ActiveSupport::Concern but with more control.
+  #
+  # @example Basic usage
+  #   module MyConcern
+  #     extend Tins::Concern
+  #
+  #     included do
+  #       attr_accessor :logger
+  #     end
+  #
+  #     def log(message)
+  #       logger&.info message
+  #     end
+  #
+  #     class_methods do
+  #       def my_class_method
+  #         # ...
+  #       end
+  #     end
+  #   end
+  #
+  #   class MyClass
+  #     include MyConcern
+  #   end
   module Concern
+    # Extends the base object with dependency tracking capabilities.
+    #
+    # This method initializes an instance variable on the base object to store
+    # dependency information.
+    #
+    # @param base [ Object ] the object being extended
     def self.extended(base)
       base.instance_variable_set("@_dependencies", [])
     end
 
+    # The append_features method includes dependencies and class methods in the
+    # base class.
+    #
+    # @param base [ Object ] the base class to include features in
+    # @return [ Boolean ] true if features were appended, false otherwise
     def append_features(base)
       if base.instance_variable_defined?("@_dependencies")
         base.instance_variable_get("@_dependencies") << self
@@ -19,6 +59,14 @@ module Tins
       end
     end
 
+    # Prepends the features of this module to the base class.
+    #
+    # This method handles the inclusion of dependencies and class methods when
+    # a module is included in a class. It manages dependency tracking and
+    # ensures proper extension of the base class with ClassMethods.
+    #
+    # @param base [Class] the class that includes this module
+    # @return [Boolean] true if the module was successfully prepended, false otherwise
     def prepend_features(base)
       if base.instance_variable_defined?("@_dependencies")
         base.instance_variable_get("@_dependencies") << self
@@ -34,6 +82,11 @@ module Tins
       end
     end
 
+    # The included method is called when the module is included in a class or
+    # module.
+    #
+    # @param base [ Object ] the class or module that includes this module
+    # @param block [ Proc ] optional block to be executed when included
     def included(base = nil, &block)
       if base.nil?
         instance_variable_defined?(:@_included_block) and
@@ -44,6 +97,11 @@ module Tins
       end
     end
 
+    # The prepended method handles the setup of a block for prepend
+    # functionality or delegates to the superclass implementation
+    #
+    # @param base [ Object ] the base object to prepend to, or nil to set up a block
+    # @param block [ Proc ] the block to be used for prepend functionality
     def prepended(base = nil, &block)
       if base.nil?
         instance_variable_defined?(:@_prepended_block) and
@@ -54,6 +112,12 @@ module Tins
       end
     end
 
+    # Defines a ClassMethods module for the current class and evaluates the
+    # given block within it.
+    #
+    # @param block [Proc] The block to be evaluated in the context of the
+    # ClassMethods module
+    # @return [Module] The ClassMethods module that was defined or retrieved
     def class_methods(&block)
       modul = const_get(:ClassMethods) if const_defined?(:ClassMethods, false)
       unless modul

data/lib/tins/date_dummy.rb

@@ -1,13 +1,34 @@
 require 'date'
 
 module Tins
+  # A module that provides dummy date functionality for testing purposes.
+  #
+  # @example Setting a dummy date
+  #   Date.dummy = Date.parse('2009-09-09')
+  #
+  # @example Using a dummy date in a block
+  #   Date.dummy Date.parse('2009-09-09') do
+  #     # Your code here
+  #   end
   module DateDummy
+    # The included method is a hook that gets called when this module is
+    # included in another class or module.
+    #
+    # It sets up date freezing functionality by extending the including
+    # class/module with special date handling methods. The method modifies the
+    # including class/module's singleton class to provide dummy date
+    # capabilities.
+    #
+    # @param modul [Object] the class or module that includes this module
     def self.included(modul)
       class << modul
         alias really_today today
 
         remove_method :today rescue nil
 
+        # Sets the dummy date value for date freezing functionality.
+        #
+        # @param value [Date, String] the date value to set as dummy
         def dummy=(value)
           if value.respond_to?(:to_str)
             value = Date.parse(value.to_str)
@@ -17,6 +38,16 @@ module Tins
           @dummy = value
         end
 
+        # The dummy method provides a way to set and temporarily override a
+        # dummy value within a block.
+        #
+        # @param value [Object] the dummy value to set, or nil to get the
+        # current dummy value
+        # @yield [] yields control to the block if a value is provided
+        # @return [Object] the current dummy value if no value parameter was
+        # provided
+        # @yieldparam value [Object] the dummy value to set within the block
+        # @yieldreturn [Object] the result of the block execution
         def dummy(value = nil)
           if value.nil?
             if defined?(@dummy)
@@ -33,6 +64,11 @@ module Tins
           end
         end
 
+        # The today method returns the current date. When a dummy date is set,
+        # it returns a duplicate of that date. Otherwise, it delegates to the
+        # actual today method implementation.
+        #
+        # @return [Date] the current date or the dummy date if set
         def today
           if dummy
             dummy.dup
@@ -42,12 +78,8 @@ module Tins
             really_today
           end
         end
-
       end
       super
     end
   end
 end
-
-require 'tins/alias'
-

data/lib/tins/date_time_dummy.rb

@@ -1,13 +1,30 @@
 require 'date'
 
 module Tins
+  # A module that provides dummy functionality for DateTime class
+  #
+  # This module allows setting a fixed date and time that will be returned by
+  # DateTime.now instead of the actual current time. This is useful for testing
+  # purposes where consistent timestamps are required.
   module DateTimeDummy
+    # The included method is a hook that gets called when this module is
+    # included in another class or module.
+    #
+    # It sets up date time freezing functionality by extending the including
+    # class/module with special date time handling methods. The method modifies
+    # the including class/module's singleton class to provide dummy date time
+    # capabilities.
+    #
+    # @param modul [Object] the class or module that includes this module
     def self.included(modul)
       class << modul
         alias really_now now
 
         remove_method :now rescue nil
 
+        # Sets the dummy value for datetime handling.
+        #
+        # @param value [DateTime, String] the datetime value to set as dummy
         def dummy=(value)
           if value.respond_to?(:to_str)
             value = DateTime.parse(value.to_str)
@@ -17,6 +34,18 @@ module Tins
           @dummy = value
         end
 
+        # The dummy method provides a way to set and restore a dummy value
+        # within a block.
+        #
+        # @param value [Object] the dummy value to set, or nil to get the
+        # current dummy value
+        #
+        # @yield [void] yields control to the block if a value is provided
+        #
+        # @return [Object] the current dummy value if no value parameter is
+        # provided
+        # @return [Object] the result of the block if a value parameter is
+        # provided
         def dummy(value = nil)
           if value.nil?
             if defined?(@dummy)
@@ -33,6 +62,11 @@ module Tins
           end
         end
 
+        # The now method returns the current time, using a dummy time if one
+        # has been set. If no dummy time is set, it delegates to the actual
+        # time retrieval method.
+        #
+        # @return [Time] the current time or a mocked time if dummy is set
         def now
           if dummy
             dummy.dup
@@ -47,5 +81,3 @@ module Tins
     end
   end
 end
-
-require 'tins/alias'

data/lib/tins/deep_dup.rb

@@ -1,5 +1,14 @@
 module Tins
+  # DeepDup module provides a method to deeply duplicate objects in Ruby.
+  #
+  # This module extends the Object class with a deep_dup method that creates a
+  # recursive copy of an object and all its nested objects.
   module DeepDup
+    # Duplicates an object deeply by marshaling and unmarshaling it. For
+    # objects that can't be marshaled, it returns the object itself.
+    #
+    # @return [Object] a deep duplicate of the object or the object itself if
+    # it can't be marshaled
     def deep_dup
       Marshal.load(Marshal.dump(self))
     rescue TypeError
@@ -7,5 +16,3 @@ module Tins
     end
   end
 end
-
-require 'tins/alias'

data/lib/tins/deprecate.rb

@@ -1,5 +1,17 @@
 module Tins
+  # A module for deprecating methods with customizable messages and warnings.
+  #
+  # @example
+  #   class MyClass
+  #     extend Tins::Deprecate
+  #     deprecate method: :old_method, new_method: :new_method
+  #   end
   module Deprecate
+    # Deprecates a method and issues a warning when called.
+    #
+    # @param method [ Symbol ] the name of the method to deprecate
+    # @param new_method [ Symbol ] the name of the replacement method
+    # @param message [ String ] the warning message to display
     def deprecate(method:, new_method: nil, message: nil)
       message ||= '[DEPRECATION] `%{method}` is deprecated. Please use `%{new_method}` instead.'
       message = message % { method: method, new_method: new_method }