unit_measurements 4.9.0 → 4.11.0

data/lib/unit_measurements/measurement.rb

@@ -3,6 +3,28 @@
 # -*- warn_indent: true -*-
 
 module UnitMeasurements
+  # @abstract
+  # The +UnitMeasurements::Measurement+ is the abstract class and serves as superclass
+  # for all the unit groups. It includes several modules that provide mathematical
+  # operations, comparison, conversion, formatting, and other functionalities.
+  #
+  # This class provides a comprehensive set of methods and functionality for working
+  # with measurements in different units. It includes robust error handling and
+  # supports conversion between units. Additionally, it ensures that measurements
+  # are consistently represented.
+  #
+  # You should not directly initialize a +Measurement+ instance. Instead, create
+  # specialized measurement types by subclassing +Measurement+ and providing
+  # specific units and conversions through the +build+ method defined in the
+  # +UnitMeasurements+ module.
+  #
+  # @see Arithmetic
+  # @see Comparison
+  # @see Conversion
+  # @see Formatter
+  # @see Math
+  # @author {Harshal V. Ladhe}[https://shivam091.github.io/]
+  # @since 1.0.0
   class Measurement
     include Arithmetic
     include Comparison
@@ -10,10 +32,61 @@ module UnitMeasurements
     include Formatter
     include Math
 
+    # Regular expression to match conversion strings.
     CONVERSION_STRING_REGEXP = /(.+?)\s?(?:\s+(?:in|to|as)\s+(.+)|\z)/i.freeze
 
-    attr_reader :quantity, :unit
+    # Quantity of the measurement.
+    attr_reader :quantity
 
+    # The unit associated with the measurement.
+    attr_reader :unit
+
+    # Initializes a new instance of +Measurement+ with a specified +quantity+
+    # and +unit+.
+    #
+    # This method is intended to be overridden by subclasses and serves as a
+    # placeholder for common initialization logic. It raises an error if called
+    # directly on the abstract +Measurement+ class.
+    #
+    # @example Initializing the measurement with scientific number and unit:
+    #   UnitMeasurements::Length.new(BigDecimal(2), "km")
+    #   => 2.0 km
+    #
+    #   UnitMeasurements::Length.new("2e+2", "km")
+    #   => 200.0 km
+    #
+    # @example Initializing the measurement with complex number and unit:
+    #   UnitMeasurements::Length.new(Complex(2, 3), "km")
+    #   => 2+3i km
+    #
+    #   UnitMeasurements::Length.new("2+3i", "km")
+    #   => 2.0+3.0i km
+    #
+    # @example Initializing the measurement with rational or mixed rational number and unit:
+    #   UnitMeasurements::Length.new(Rational(2, 3), "km")
+    #   => 0.6666666666666666 km
+    #
+    #   UnitMeasurements::Length.new(2/3r, "km")
+    #   => 2/3 km
+    #
+    #   UnitMeasurements::Length.new("2/3", "km")
+    #   => 0.6666666666666666 km
+    #
+    #   UnitMeasurements::Length.new("½", "km")
+    #   => 0.5 km
+    #
+    # @example Initializing the measurement with ratio and unit:
+    #   UnitMeasurements::Length.new("1:2", "km")
+    #   => 0.5 km
+    #
+    # @param [Numeric|String] quantity The quantity of the measurement.
+    # @param [String|Unit] unit The unit of the measurement.
+    #
+    # @raise [BaseError] If +quantity+ or +unit+ is blank.
+    #
+    # @see BaseError
+    # @author {Harshal V. Ladhe}[https://shivam091.github.io/]
+    # @since 1.0.0
     def initialize(quantity, unit)
       raise BaseError, "Quantity cannot be blank." if quantity.blank?
       raise BaseError, "Unit cannot be blank." if unit.blank?
@@ -22,6 +95,20 @@ module UnitMeasurements
       @unit = unit_from_unit_or_name!(unit)
     end
 
+    # Converts the measurement to a +target_unit+.
+    #
+    # @example
+    #   UnitMeasurements::Length.new(1, "m").convert_to("cm")
+    #   => 100.0 cm
+    #
+    # @param [String|Symbol] target_unit The target unit for conversion.
+    #
+    # @return [Measurement]
+    #   A new +Measurement+ instance with the converted +quantity+ and
+    #   +target unit+.
+    #
+    # @author {Harshal V. Ladhe}[https://shivam091.github.io/]
+    # @since 1.0.0
     def convert_to(target_unit)
       target_unit = unit_from_unit_or_name!(target_unit)
 
@@ -31,24 +118,61 @@ module UnitMeasurements
 
       self.class.new((quantity * conversion_factor), target_unit)
     end
-    [:to, :in, :as].each { |method_alias| alias_method method_alias, :convert_to }
+    alias_method :to, :convert_to
+    alias_method :in, :convert_to
+    alias_method :as, :convert_to
 
+    # Converts the measurement to a +target_unit+ and updates the current instance.
+    #
+    # @example
+    #   UnitMeasurements::Length.new(1, "m").convert_to!("cm")
+    #   => 100.0 cm
+    #
+    # @param [String|Symbol] target_unit The target unit for conversion.
+    #
+    # @return [Measurement]
+    #   The current +Measurement+ instance with updated +quantity+ and +unit+.
+    #
+    # @author {Harshal V. Ladhe}[https://shivam091.github.io/]
+    # @since 1.0.0
     def convert_to!(target_unit)
       measurement = convert_to(target_unit)
       @quantity, @unit = measurement.quantity, measurement.unit
 
       self
     end
-    [:to!, :in!, :as!].each { |method_alias| alias_method method_alias, :convert_to! }
+    alias_method :to!, :convert_to!
+    alias_method :in!, :convert_to!
+    alias_method :as!, :convert_to!
 
+    # Returns an object representation of the +Measurement+.
+    #
+    # @param [TrueClass|FalseClass] dump If +true+, returns the dump representation.
+    #
+    # @return [Object] An object representation of the +Measurement+.
+    #
+    # @author {Harshal V. Ladhe}[https://shivam091.github.io/]
+    # @since 1.0.0
     def inspect(dump: false)
       dump ? super() : to_s
     end
 
+    # Returns a string representation of the +Measurement+.
+    #
+    # @return [String] A string representation of the +Measurement+.
+    #
+    # @author {Harshal V. Ladhe}[https://shivam091.github.io/]
+    # @since 1.0.0
     def to_s
       "#{quantity} #{unit}"
     end
 
+    # Returns the +quantity+ of the +measurement+.
+    #
+    # @return [Numeric] Quantity of the measurement.
+    #
+    # @author {Harshal V. Ladhe}[https://shivam091.github.io/]
+    # @since 1.5.0
     def quantity
       case @quantity
       when Rational
@@ -61,14 +185,90 @@ module UnitMeasurements
     class << self
       extend Forwardable
 
-      def unit_group
-        raise BaseError, "`Measurement` does not have a `unit_group` object. You cannot directly use `Measurement`. Instead, build a new unit group by calling `UnitMeasurements.build`."
-      end
-
+      # Methods delegated from the unit group.
       def_delegators :unit_group, :primitive, :units, :unit_names, :unit_with_name_and_aliases,
                      :unit_names_with_aliases, :unit_for, :unit_for!, :defined?,
                      :unit_or_alias?, :[]
 
+      # Parses an input string and returns a +Measurement+ instance depending on
+      # the input string. This method first normalizes the +input+ internally,
+      # using the +Normalizer+ before parsing it using the +Parser+.
+      #
+      # If only the source unit is provided, it returns a new +Measurement+
+      # instance with the quantity in the source unit.If both source and target
+      # units are provided in the input string, it returns a new +Measurement+
+      # instance with the quantity converted to the target unit.
+      #
+      # @example Parsing string representing a complex number and source unit:
+      #   UnitMeasurements::Length.parse("2+3i km")
+      #   => 2.0+3.0i km
+      #
+      # @example Parsing string representing a complex number, source, and target units:
+      #   UnitMeasurements::Length.parse("2+3i km to m")
+      #   => 2000.0+3000.0i m
+      #
+      # @example Parsing string representing a rational or mixed rational number and source unit:
+      #   UnitMeasurements::Length.parse("½ km")
+      #   => 0.5 km
+      #
+      #   UnitMeasurements::Length.parse("2/3 km")
+      #   => 0.666666666666667 km
+      #
+      #   UnitMeasurements::Length.parse("2 ½ km")
+      #   => 2.5 km
+      #
+      #   UnitMeasurements::Length.parse("2 1/2 km")
+      #   => 2.5 km
+      #
+      # @example Parsing string representing a rational or mixed rational number, source, and target units:
+      #   UnitMeasurements::Length.parse("½ km to m")
+      #   => 500.0 km
+      #
+      #   UnitMeasurements::Length.parse("2/3 km to m")
+      #   => 666.666666666667 m
+      #
+      #   UnitMeasurements::Length.parse("2 ½ km to m")
+      #   => 2500.0 m
+      #
+      #   UnitMeasurements::Length.parse("2 1/2 km to m")
+      #   => 2500.0 m
+      #
+      # @example Parsing string representing a scientific number and source unit:
+      #   UnitMeasurements::Length.parse("2e² km")
+      #   => 200.0 km
+      #
+      #   UnitMeasurements::Length.parse("2e+2 km")
+      #   => 200.0 km
+      #
+      #   UnitMeasurements::Length.parse("2e⁻² km")
+      #   => 0.02 km
+      #
+      # @example Parsing string representing a scientific number, source, and target units:
+      #
+      #   UnitMeasurements::Length.parse("2e+2 km to m")
+      #   => 200000.0 m
+      #
+      #   UnitMeasurements::Length.parse("2e⁻² km to m")
+      #   => 20.0 m
+      #
+      # @example Parsing string representing a ratio and source unit:
+      #   UnitMeasurements::Length.parse("1:2 km")
+      #   => 0.5 km
+      #
+      # @example Parsing string representing a ratio, source, and target units:
+      #   UnitMeasurements::Length.parse("1:2 km to m")
+      #   => 500.0 m
+      #
+      # @param [String] input The input string to be parsed.
+      #
+      # @return [Measurement] The +Measurement+ instance.
+      #
+      # @see Parser
+      # @see Normalizer
+      # @see CONVERSION_STRING_REGEXP
+      # @see _parse
+      # @author {Harshal V. Ladhe}[https://shivam091.github.io/]
+      # @since 1.0.0
       def parse(input)
         input = Normalizer.normalize(input)
         source, target = input.match(CONVERSION_STRING_REGEXP)&.captures
@@ -78,6 +278,30 @@ module UnitMeasurements
 
       private
 
+      # @private
+      # The class attribute representing an instance of +UnitGroup+.
+      #
+      # @return [UnitGroup] An instance of +UnitGroup+.
+      #
+      # @raise [BaseError]
+      #   If directly invoked on +Measurement+ rather than its subclasses.
+      #
+      # @see UnitGroup
+      # @author {Harshal V. Ladhe}[https://shivam091.github.io/]
+      # @since 1.0.0
+      def unit_group
+        raise BaseError, "`Measurement` does not have a `unit_group` instance. You cannot directly use `Measurement`. Instead, build a new unit group by calling `UnitMeasurements.build`."
+      end
+
+      # @private
+      # Parses the normalized string to return the +Measurement+ instance.
+      #
+      # @param [String] string String to be parsed.
+      #
+      # @return [Measurement] The +Measurement+ instance.
+      #
+      # @author {Harshal V. Ladhe}[https://shivam091.github.io/]
+      # @since 1.0.0
       def _parse(string)
         quantity, unit = Parser.parse(string)
 
@@ -87,6 +311,15 @@ module UnitMeasurements
 
     private
 
+    # @private
+    # Converts the measurement quantity to a suitable format for internal use.
+    #
+    # @param [Numeric|String] quantity The quantity of the measurement.
+    #
+    # @return [Numeric] The converted quantity.
+    #
+    # @author {Harshal V. Ladhe}[https://shivam091.github.io/]
+    # @since 1.0.0
     def convert_quantity(quantity)
       case quantity
       when Float
@@ -103,8 +336,18 @@ module UnitMeasurements
       end
     end
 
+    # @private
+    # Returns the +Unit+ instance associated with the +value+ provided.
+    #
+    # @param [String|Unit] value
+    #   The value representing a unit name or +Unit+ instance.
+    #
+    # @return [Unit] The +Unit+ instance associated with +value+.
+    #
+    # @author {Harshal V. Ladhe}[https://shivam091.github.io/]
+    # @since 1.0.0
     def unit_from_unit_or_name!(value)
-      value.is_a?(Unit) ? value : self.class.unit_group.unit_for!(value)
+      value.is_a?(Unit) ? value : self.class.send(:unit_group).unit_for!(value)
     end
   end
 end

data/lib/unit_measurements/normalizer.rb

@@ -3,7 +3,22 @@
 # -*- warn_indent: true -*-
 
 module UnitMeasurements
+  # The +UnitMeasurements::Normalizer+ class defines useful methods for handling
+  # input strings that may contain non-standard representations of numbers.
+  #
+  # It maps special symbols of exponents and fractions to their standard
+  # counterparts. The class ensures consistent handling of input strings within
+  # the library.
+  #
+  # @see Measurement
+  # @author {Harshal V. Ladhe}[https://shivam091.github.io/]
+  # @since 1.0.0
   class Normalizer
+    # A mapping of superscript numbers, plus, and minus signs to their regular
+    # counterparts.
+    #
+    # @author {Harshal V. Ladhe}[https://shivam091.github.io/]
+    # @since 1.0.0
     EXPONENTS_SYMBOLS = {
       "⁰" => "0",
       "¹" => "1",
@@ -19,6 +34,10 @@ module UnitMeasurements
       "⁻" => "-",
     }.freeze
 
+    # A mapping of special fraction symbols to their equivalent numeric fractions.
+    #
+    # @author {Harshal V. Ladhe}[https://shivam091.github.io/]
+    # @since 1.0.0
     FRACTIONS_SYMBOLS = {
       "¼"  => "1/4",
       "½"  => "1/2",
@@ -41,11 +60,81 @@ module UnitMeasurements
       "↉"  => "0/3",
     }.freeze
 
-    EXPONENT_REGEX = /([\d]+[Ee]?[+-]?)(#{EXPONENTS_SYMBOLS.keys.join("|")})/.freeze
-    FRACTION_REGEX = /(#{FRACTIONS_SYMBOLS.keys.join("|")})/.freeze
-    RATIO_REGEX    = /([\d]+):([\d]+)/.freeze
+    # Matches a combination of digits, optional exponent notation, and optional plus or minus sign.
+    #
+    # @author {Harshal V. Ladhe}[https://shivam091.github.io/]
+    # @since 1.0.0
+    EXPONENT_REGEX = /
+                       (                                     # Start of the first capturing group
+                         [\d]+                               # One or more digits
+                         [Ee]?                               # Match an optional 'E' or 'e' for scientific notation
+                         [+-]?                               # Match an optional plus or minus sign
+                       )                                     # End of the first capturing group
+                       (                                     # Start of the second capturing group
+                         #{EXPONENTS_SYMBOLS.keys.join("|")} # Match any of the exponent symbols defined in EXPONENTS_SYMBOLS
+                       )                                     # End of the second capturing group
+                     /x.freeze
+
+    # Matches special fraction symbols.
+    #
+    # @author {Harshal V. Ladhe}[https://shivam091.github.io/]
+    # @since 1.0.0
+    FRACTION_REGEX = /
+                       (                                     # Start of the capturing group
+                         #{FRACTIONS_SYMBOLS.keys.join("|")} # Match any of the fraction symbols defined in FRACTIONS_SYMBOLS
+                       )                                     # End of the capturing group
+                     /x.freeze
+
+    # Matches a ratio in the format of +numerator:denominator+.
+    #
+    # @author {Harshal V. Ladhe}[https://shivam091.github.io/]
+    # @since 1.0.0
+    RATIO_REGEX    = /
+                       (                                     # Start of the first capturing group
+                         [\d]+                               # One or more digits, representing the numerator
+                       )                                     # End of the first capturing group
+                       :                                     # Match a colon (:)
+                       (                                     # Start of the second capturing group
+                         [\d]+                               # One or more digits, representing the denominator
+                       )                                     # End of the second capturing group
+                     /x.freeze
+
 
     class << self
+      # Normalizes a string containing special symbols of exponents and fractions,
+      # and ratio.
+      #
+      # The +normalize+ method in the +UnitMeasurements::Normalizer+ module processes
+      # the input string to replace special symbols with their equivalent representations,
+      # such as converting superscript numbers to regular numbers, special fraction
+      # symbols to their numeric fractions, and ratios to fractional format, and
+      # remove leading and trailing whitespaces from the +string+.
+      #
+      # @example Normalizing special symbol of fraction:
+      #   UnitMeasurements::Normalizer.normalize("¾")
+      #   => "3/4"
+      #
+      #   UnitMeasurements::Normalizer.normalize(" 1¾ ")
+      #   => "1 3/4"
+      #
+      # @example Normalizing ratio:
+      #   UnitMeasurements::Normalizer.normalize("1:2")
+      #   => "1/2"
+      #
+      # @example Normalizing special symbol of exponents:
+      #   UnitMeasurements::Normalizer.normalize("1e⁺²")
+      #   => "1e+2"
+      #
+      #   UnitMeasurements::Normalizer.normalize("1e⁻²")
+      #   => "1e-2"
+      #
+      # @param [String] string The input string to be normalized.
+      #
+      # @return [String] The normalized version of the input string.
+      #
+      # @see Measurement
+      # @author {Harshal V. Ladhe}[https://shivam091.github.io/]
+      # @since 1.0.0
       def normalize(string)
         string.dup.tap do |str|
           if str =~ Regexp.new(EXPONENT_REGEX)

data/lib/unit_measurements/parser.rb

@@ -3,18 +3,144 @@
 # -*- warn_indent: true -*-
 
 module UnitMeasurements
+  # The +UnitMeasurements::Parser+ class provides methods for parsing strings to
+  # extract quantity and associated unit. It can handle various formats, including
+  # complex numbers, scientific numbers, and rational numbers for the +quantity+.
+  #
+  # @see Measurement
+  # @author {Harshal V. Ladhe}[https://shivam091.github.io/]
+  # @since 1.0.0
   class Parser
-    UNIT_REGEX        = /([^\d\s\/].*)/.freeze
+    # Matches any character sequence that does not consist of digits, whitespace,
+    # or forward slashes.
+    #
+    # @author {Harshal V. Ladhe}[https://shivam091.github.io/]
+    # @since 1.0.0
+    UNIT_REGEX        = /
+                          (                    # Start of the capturing group
+                            [^\d\s\/]          # Match any character that is not a digit, whitespace, or a forward slash
+                            .*                 # Match zero or more of any character (except for a newline)
+                          )                    # End of the capturing group
+                        /x.freeze
 
-    SCIENTIFIC_NUMBER = /([+-]?\d*\.?\d+(?:[Ee][+-]?)?\d*)/.freeze
-    RATIONAL_NUMBER   = /([+-]?\d+\s+)?((\d+)\/(\d+))/.freeze
-    COMPLEX_NUMBER    = /#{SCIENTIFIC_NUMBER}#{SCIENTIFIC_NUMBER}i/.freeze
+    # Matches scientific numbers (e.g., +1.23e-4+).
+    #
+    # @author {Harshal V. Ladhe}[https://shivam091.github.io/]
+    # @since 1.0.0
+    SCIENTIFIC_NUMBER = /
+                          (                    # Start of a capturing group (denoted by parentheses)
+                            [+-]?              # Match an optional plus or minus sign (+ or -)
+                            \d*                # Match zero or more digits
+                            \.?                # Match an optional dot (.)
+                            \d+                # Match one or more digits
+                            (?:                # Start of a non-capturing group
+                              [Ee]             # Match either 'E' or 'e'
+                              [+-]?            # Match an optional plus or minus sign (+ or -)
+                            )?                 # End of the non-capturing group; ? makes it optional
+                            \d*                # Match zero or more digits
+                          )                    # End of the capturing group
+                        /x.freeze
 
-    SCIENTIFIC_REGEX  = /\A#{SCIENTIFIC_NUMBER}\s*#{UNIT_REGEX}?\z/.freeze
-    RATIONAL_REGEX    = /\A#{RATIONAL_NUMBER}\s*#{UNIT_REGEX}?\z/.freeze
-    COMPLEX_REGEX     = /\A#{COMPLEX_NUMBER}\s*#{UNIT_REGEX}?\z/.freeze
+    # Matches rational numbers (e.g., +1/2+).
+    #
+    # @author {Harshal V. Ladhe}[https://shivam091.github.io/]
+    # @since 1.0.0
+    RATIONAL_NUMBER   = /
+                          (                    # Start of the first capturing group
+                            [+-]?              # Match an optional plus or minus sign (+ or -)
+                            \d+                # Match one or more digits
+                            \s+                # Match one or more whitespace characters
+                          )?                   # End of the first capturing group
+                          (                    # Start of the second capturing group (the fraction part)
+                            (\d+)              # Start of the third capturing group (one or more digits, the numerator)
+                            \/                 # Match a forward slash - the division symbol
+                            (\d+)              # Start of the fourth capturing group (one or more digits, the denominator)
+                          )                    # End of the second capturing group (the fraction part)
+                        /x.freeze
+
+    # Matches complex numbers (e.g., +1-2i+).
+    #
+    # @author {Harshal V. Ladhe}[https://shivam091.github.io/]
+    # @since 1.0.0
+    COMPLEX_NUMBER    = /
+                          #{SCIENTIFIC_NUMBER} # Pattern for scientific number
+                          #{SCIENTIFIC_NUMBER} # Pattern for scientific number
+                          i                    # Match the letter 'i' (the imaginary unit)
+                        /x.freeze
+
+    # Matches strings containing scientific numbers and unit.
+    #
+    # @author {Harshal V. Ladhe}[https://shivam091.github.io/]
+    # @since 1.0.0
+    SCIENTIFIC_REGEX  = /
+                          \A                   # Anchor at the start of the string
+                          #{SCIENTIFIC_NUMBER} # Match a scientific number (as defined earlier)
+                          \s*                  # Match zero or more whitespace characters
+                          #{UNIT_REGEX}?       # Match a unit, the '?' makes it optional
+                          \z                   # Anchor at the end of the string
+                        /x.freeze
+
+    # Matches strings containing rational numbers and unit.
+    #
+    # @author {Harshal V. Ladhe}[https://shivam091.github.io/]
+    # @since 1.0.0
+    RATIONAL_REGEX    = /
+                          \A                   # Anchor at the start of the string
+                          #{RATIONAL_NUMBER}   # Match a rational number (as defined earlier)
+                          \s*                  # Match zero or more whitespace characters
+                          #{UNIT_REGEX}?       # Match a unit, the '?' makes it optional
+                          \z
+                        /x.freeze
+
+    # Matches strings containing complex numbers and unit.
+    #
+    # @author {Harshal V. Ladhe}[https://shivam091.github.io/]
+    # @since 1.0.0
+    COMPLEX_REGEX     = /
+                          \A                   # Anchor at the start of the string
+                          #{COMPLEX_NUMBER}    # Match a complex number (as defined earlier)
+                          \s*                  # Match zero or more whitespace characters
+                          #{UNIT_REGEX}?       # Match a unit, the '?' makes it optional
+                          \z
+                        /x.freeze
 
     class << self
+      # Parses a string to extract a +quantity+ and its associated +unit+. This
+      # method first extracts a +quantity+ and converts it to +Float+ before
+      # returning it.
+      #
+      # To get the correct parsed results, you must first normalize the +string+
+      # with +Normalizer+ if using the parser standalone.
+      #
+      # @example Parsing string representing a complex number:
+      #   UnitMeasurements::Parser.parse("1+2i m")
+      #   => [(1.0+2.0i), "m"]
+      #
+      # @example Parsing string representing a rational number:
+      #   UnitMeasurements::Parser.parse("1/2 m")
+      #   => [0.5, "m"]
+      #
+      # @example Parsing string representing a mixed rational number:
+      #   UnitMeasurements::Parser.parse("2 1/2 km")
+      #   => [2.5, "km"]
+      #
+      # @example Parsing string representing a scientific number:
+      #   UnitMeasurements::Parser.parse("1e+2 km")
+      #   => [100.0, "km"]
+      #
+      # @param [String] string
+      #   The input string containing a +quantity+ and an optional +unit+.
+      #
+      # @return [Array<Numeric, String|NilClass>]
+      #   The parsed +quantity+ and the +unit+ associated with it (or +nil+ if
+      #   no unit is specified in the +string+).
+      #
+      # @raise [ParseError] If the string is invalid and cannot be parsed.
+      #
+      # @see Measurement
+      # @see Normalizer
+      # @author {Harshal V. Ladhe}[https://shivam091.github.io/]
+      # @since 1.0.0
       def parse(string)
         case string
         when COMPLEX_REGEX    then parse_complex(string)
@@ -26,6 +152,18 @@ module UnitMeasurements
 
       private
 
+      # @private
+      # Parses a string representing a complex number with an optional unit.
+      #
+      # @param [String] string
+      #   The input string containing a complex number and an optional unit.
+      #
+      # @return [Array<Numeric, String|NilClass>]
+      #   The parsed complex number and the associated unit (or +nil+ if no unit
+      #   is specified in the string).
+      #
+      # @author {Harshal V. Ladhe}[https://shivam091.github.io/]
+      # @since 1.0.0
       def parse_complex(string)
         real, imaginary, unit = string.match(COMPLEX_REGEX)&.captures
         quantity = Complex(real.to_f, imaginary.to_f)
@@ -33,6 +171,18 @@ module UnitMeasurements
         [quantity, unit]
       end
 
+      # @private
+      # Parses a string representing a scientific number with an optional unit.
+      #
+      # @param [String] string
+      #   The input string containing a scientific number and an optional unit.
+      #
+      # @return [Array<Numeric, String|NilClass>]
+      #   The parsed scientific number and the associated unit (or +nil+ if no unit
+      #   is specified in the string).
+      #
+      # @author {Harshal V. Ladhe}[https://shivam091.github.io/]
+      # @since 1.0.0
       def parse_scientific(string)
         whole, unit = string.match(SCIENTIFIC_REGEX)&.captures
         quantity = whole.to_f
@@ -40,6 +190,18 @@ module UnitMeasurements
         [quantity, unit]
       end
 
+      # @private
+      # Parses a string representing a rational number with an optional unit.
+      #
+      # @param [String] string
+      #   The input string containing a rational number and an optional unit.
+      #
+      # @return [Array<Numeric, String|NilClass>]
+      #   The parsed rational number and the associated unit (or +nil+ if no unit
+      #   is specified in the string).
+      #
+      # @author {Harshal V. Ladhe}[https://shivam091.github.io/]
+      # @since 1.0.0
       def parse_rational(string)
         whole, _, numerator, denominator, unit = string.match(RATIONAL_REGEX)&.captures