lib/unit_measurements/measurement.rb in unit_measurements-5.0.0 vs lib/unit_measurements/measurement.rb in unit_measurements-5.1.0

@@ -31,16 +31,29 @@
     include Conversion
     include Formatter
     include Math
 
     # Regular expression to match conversion strings.
+    #
+    # @author {Harshal V. Ladhe}[https://shivam091.github.io/]
+    # @since 1.0.0
     CONVERSION_STRING_REGEXP = /(.+?)\s?(?:\s+(?:in|to|as)\s+(.+)|\z)/i.freeze
 
     # Quantity of the measurement.
+    #
+    # @return [Numeric] Quantity of the measurement.
+    #
+    # @author {Harshal V. Ladhe}[https://shivam091.github.io/]
+    # @since 1.0.0
     attr_reader :quantity
 
     # The unit associated with the measurement.
+    #
+    # @return [Unit] The +unit+ instance associated with the measurement.
+    #
+    # @author {Harshal V. Ladhe}[https://shivam091.github.io/]
+    # @since 1.0.0
     attr_reader :unit
 
     # Initializes a new instance of +Measurement+ with a specified +quantity+
     # and +unit+.
     #
@@ -53,10 +66,16 @@
     #   => 2.0 km
     #
     #   UnitMeasurements::Length.new("2e+2", "km")
     #   => 200.0 km
     #
+    #   UnitMeasurements::Length.new("2e²", "km")
+    #   => 200.0 km
+    #
+    #   UnitMeasurements::Length.new("2e⁻²", "km")
+    #   => 0.02 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")
@@ -73,10 +92,13 @@
     #   => 0.6666666666666666 km
     #
     #   UnitMeasurements::Length.new("½", "km")
     #   => 0.5 km
     #
+    #   UnitMeasurements::Length.new("2 ½", "km")
+    #   => 2.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.
@@ -93,11 +115,12 @@
 
       @quantity = convert_quantity(quantity)
       @unit = unit_from_unit_or_name!(unit)
     end
 
-    # Converts the measurement to a +target_unit+.
+    # Converts the measurement to a +target_unit+ and returns new instance of the
+    # measurement.
     #
     # @example
     #   UnitMeasurements::Length.new(1, "m").convert_to("cm")
     #   => 100.0 cm
     #
@@ -140,10 +163,11 @@
     # @param [String|Symbol] target_unit The target unit for conversion.
     #
     # @return [Measurement]
     #   The current +Measurement+ instance with updated +quantity+ and +unit+.
     #
+    # @see #convert_to
     # @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
@@ -273,11 +297,12 @@
       # @return [Measurement] The +Measurement+ instance.
       #
       # @see Parser
       # @see Normalizer
       # @see CONVERSION_STRING_REGEXP
-      # @see _parse
+      # @see ._parse
+      # @see #convert_to
       # @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
@@ -307,9 +332,10 @@
       #
       # @param [String] string String to be parsed.
       #
       # @return [Measurement] The +Measurement+ instance.
       #
+      # @see Parser.parse
       # @author {Harshal V. Ladhe}[https://shivam091.github.io/]
       # @since 1.0.0
       def _parse(string)
         quantity, unit = Parser.parse(string)