unit_measurements 4.9.0 → 4.11.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 47fa12ab5aef0b04a4c5c0144878e0d7493b0ffba91c046633df4512b38b8fc5
-  data.tar.gz: 889a7b19a632a2fbdbe7cfc8efa2f917b792ffb76cf75922001e342533c06b67
+  metadata.gz: 60c27b3d75f3b92e616011aecc0f220ef26f1a2e0828bcc5c85b2d0cadd3b81b
+  data.tar.gz: d9d8fd3e291b6cb8391bd45184f09432c1ed9808d80cc0124f26d889f578f680
 SHA512:
-  metadata.gz: 2a70f8eb32af057207c1846a2d6678abca3f683bc5cb7f9278bdc45f3e31f6d330ad23f2c146e4ad2a192d2a245729b7dfe82cfb68926f469b77ed4508309bf0
-  data.tar.gz: 6c36c79eb4c7b1d3edaf9fe66e034ad5d8cea4d0ae2773f30dcf5a1f9ba0cf807cbd5793cf05590d8ec7d2a3cd21fb107358ff2e93f980c7cb356aa43bb8f1fb
+  metadata.gz: 5612e9192c1c59076d94072d2e7c6d7838c4022ff152124ece55a9d4986fc8008759947469b0310c6c6dfa7045cb732c1e46d993585f907c595b9b342d5abad8
+  data.tar.gz: bbe280e459ae3ccfe7cbed4fdf56bd4f0666b4f02e4b91ba1b4b46747f7fb717a9ac77590eb7767723c23a2eca1993a95e803d5f661dec5530b392e4d633738b

data/.github/workflows/main.yml

@@ -8,23 +8,24 @@ on:
       - main
 jobs:
   build:
+    name: Ruby ${{ matrix.ruby }}
     runs-on: ubuntu-latest
     env:
       RAILS_ENV: test
       CC_TEST_REPORTER_ID: ${{ secrets.CC_TEST_REPORTER_ID }}
-    name: Ruby ${{ matrix.ruby }}
     strategy:
       matrix:
         ruby:
           - "3.2.2"
     steps:
-    - uses: actions/checkout@v3
-    - name: Set up Ruby
-      uses: ruby/setup-ruby@v1
-      with:
-        ruby-version: ${{ matrix.ruby }}
-        bundler-cache: true
-    - name: Run test cases
-      run: bundle exec rake
-    - name: Publish code coverage
-      uses: paambaati/codeclimate-action@v5.0.0
+      - name: Checkout Repository
+        uses: actions/checkout@v3
+      - name: Set up Ruby
+        uses: ruby/setup-ruby@v1
+        with:
+          ruby-version: ${{ matrix.ruby }}
+          bundler-cache: true
+      - name: Run test cases
+        run: bundle exec rake
+      - name: Publish code coverage
+        uses: paambaati/codeclimate-action@v5.0.0

data/.github/workflows/pages.yml

@@ -0,0 +1,31 @@
+name: Publish Documentation to GitHub Pages
+on:
+  push:
+    branches:
+      - main
+jobs:
+  build:
+    name: Publish Documentation to GitHub Pages ${{ matrix.ruby }}
+    runs-on: ubuntu-latest
+    permissions:
+      contents: write
+    strategy:
+      matrix:
+        ruby:
+          - "3.2.2"
+    steps:
+      - name: Checkout Repository
+        uses: actions/checkout@v3
+      - name: Set Up Ruby
+        uses: ruby/setup-ruby@v1
+        with:
+          ruby-version: ${{ matrix.ruby }}
+      - name: Install Dependencies
+        run: gem install yard
+      - name: Generate Documentation
+        run: yardoc --private --exclude "unit_groups/*"
+      - name: Deploy to GitHub Pages
+        uses: peaceiris/actions-gh-pages@v3.9.3
+        with:
+          github_token: ${{ secrets.GITHUB_TOKEN }}
+          publish_dir: ./doc

data/CHANGELOG.md

@@ -1,3 +1,21 @@
+## [4.11.0](https://github.com/shivam091/unit_measurements/compare/v4.10.0...v4.11.0) - 2023-10-15
+
+### What's new
+
+- Added new units in `length` (ch, th, ftm, fur, nmi, rod, au, pc) unit group.
+- Added new units in `weight` (ct, Da, lb, st, oz, gr, ozt, dwt, dr, slug) unit group.
+
+----------
+
+## [4.10.0](https://github.com/shivam091/unit_measurements/compare/v4.9.0...v4.10.0) - 2023-10-14
+
+### What's new
+
+- Added documentation for all modules, classes, and methods.
+- Updated readme and added workflow for publishing documentation using `yardoc`.
+
+----------
+
 ## [4.9.0](https://github.com/shivam091/unit_measurements/compare/v4.8.0...v4.9.0) - 2023-10-13
 
 ### What's new
@@ -356,6 +374,7 @@
 - Added support to build `si` units.
 - Added support to parse `Complex`, `Rational`, `Scientific` numbers, and `ratios`.
 - Added support to convert quantity between two units using `#convert_to`, `#convert_to!`, and `#parse` methods.
+- Added normalizer to normalize special characters used in numbers.
 
 ----------
 

data/Gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: .
   specs:
-    unit_measurements (4.9.0)
+    unit_measurements (4.11.0)
       activesupport (~> 7.0)
 
 GEM

data/README.md

@@ -9,7 +9,7 @@ A library that encapsulate measurements and their units in Ruby.
 [![Test Coverage](https://api.codeclimate.com/v1/badges/b8aec9bffa356d108784/test_coverage)](https://codeclimate.com/github/shivam091/unit_measurements/test_coverage)
 [![License](https://img.shields.io/badge/License-MIT-blue.svg)](https://github.com/shivam091/unit_measurements/blob/main/LICENSE.md)
 
-**Harshal V. Ladhe, Master of Computer Science.**
+[Harshal V. Ladhe, Master of Computer Science.](https://shivam091.github.io)
 
 ## Introduction
 
@@ -26,8 +26,9 @@ The `unit_measurements` gem is designed to simplify the handling of units for sc
 
 1. It provides easy conversion between units.
 2. It is lightweight and easily extensible to include other units and conversions.
-2. It has built in support for various [unit groups](units.md).
-4. It can convert `complex`, `fractional`, `mixed fractional`, `scientific` numbers, and `ratios`.
+3. It has built in support for various [unit groups](https://github.com/shivam091/unit_measurements/blob/main/units.md).
+4. It has well organized and very descriptive documentation published [here](https://shivam091.github.io/unit_measurements).
+5. It can convert `complex`, `fractional`, `mixed fractional`, `scientific` numbers, and `ratios`.
 
 ## Disclaimer
 
@@ -113,27 +114,17 @@ UnitMeasurements::Length.parse("1 km to m")
 **Parse scientific numbers, source unit, and (or) target unit:**
 
 ```ruby
-UnitMeasurements::Length.new(BigDecimal(2), "km").convert_to("m")
-#=> 20000.0 m
-UnitMeasurements::Length.new("2e+2", "km").convert_to("m")
-#=> 200000.0 m
-UnitMeasurements::Length.parse("2e² km").convert_to("m")
+UnitMeasurements::Length.parse("2e+2 km").convert_to("m")
 #=> 200000.0 m
 UnitMeasurements::Length.parse("2e+2 km to m")
 #=> 200000.0 m
-UnitMeasurements::Length.parse("2e⁻² km to m")
-#=> 20.0 m
 ```
-
-Supported special characters for exponents are `⁰`, `¹`, `²`, `³`, `⁴`, `⁵`, `⁶`, `⁷`, `⁸`, `⁹`, `⁺`, `⁻`.
+You can check supported special characters for exponents
+[here](https://shivam091.github.io/unit_measurements/UnitMeasurements/Normalizer.html).
 
 **Parse complex numbers, source unit, and (or) target unit:**
 
 ```ruby
-UnitMeasurements::Length.new(Complex(2, 3), "km").convert_to("m")
-#=> 2000.0+3000.0i m
-UnitMeasurements::Length.new("2+3i", "km").convert_to("m")
-#=> 2000.0+3000.0i m
 UnitMeasurements::Length.parse("2+3i km").convert_to("m")
 #=> 2000.0+3000.0i m
 UnitMeasurements::Length.parse("2+3i km to m")
@@ -143,12 +134,6 @@ UnitMeasurements::Length.parse("2+3i km to m")
 **Parse fractional/mixed fractional numbers, source unit, and (or) target unit:**
 
 ```ruby
-UnitMeasurements::Length.new(Rational(2, 3), "km").convert_to("m")
-#=> 666.666666666667 m
-UnitMeasurements::Length.new("2/3", "km").convert_to("m")
-#=> 666.666666666667 m
-UnitMeasurements::Length.new("½", "km").convert_to("m")
-#=> 500.0 m
 UnitMeasurements::Length.parse("2 ½ km").convert_to("m")
 #=> 2500.0 m
 UnitMeasurements::Length.parse("2/3 km").convert_to("m")
@@ -161,7 +146,8 @@ UnitMeasurements::Length.parse("2 ½ km to m")
 #=> 2500.0 m
 ```
 
-Supported special characters for fractional notations are `¼`, `½`, `¾`, `⅓`, `⅔`, `⅕`, `⅖`, `⅗`, `⅘`, `⅙`, `⅚`, `⅐`, `⅛`, `⅜`, `⅝`, `⅞`, `⅑`, `⅒`, `↉`, `⁄`.
+You can check supported special characters for fractional notations
+[here](https://shivam091.github.io/unit_measurements/UnitMeasurements/Normalizer.html).
 
 **Parse ratios, source unit, and (or) target unit:**
 
@@ -188,6 +174,9 @@ UnitMeasurements::Length.new(100, "m").to("in").format("%.4<quantity>f")
 #=> "3937.0079"
 ```
 
+You can check more about formatting along with their examples
+[here](https://shivam091.github.io/unit_measurements/UnitMeasurements/Formatter.html).
+
 **Extract the unit and the quantity from measurement:**
 
 ```ruby
@@ -216,14 +205,14 @@ UnitMeasurements::Length.units
 
 ```ruby
 UnitMeasurements::Length.unit_names
-#=> ["m", "km", "mi", "ft", "in", "yd", ...]
+#=> ["ft", "in", "m", "mi", "yd"]
 ```
 
 **See all valid units of the unit group along with their aliases:**
 
 ```ruby
 UnitMeasurements::Length.unit_names_with_aliases
-#=> ["g", "meter", "metre", "meters", "metres", "km", "kilometer", "kilometre", "kilometers", "kilometres", "in", "inch", "inches", "yd", "yard", "yards", ...]
+#=> ["\"", "'", "feet", "foot", "ft", "in", "inch", "inches", "m", "meter", "meters", "metre", "metres", "mi", "mile", "miles", "yard", "yards", "yd"]
 ```
 
 **Finding units within the unit group:**
@@ -265,62 +254,44 @@ UnitMeasurements::Length.unit_or_alias?("metre")
 
 You have ability to compare the measurements with the same or different units within the same unit group.
 For example, comparing length with length will work, comparing a length with a area would fail.
-Supported comparisons and methods are `==`, `!=`, `<`, `>`, `<=`, `>=`, `between?`, and `clamp`.
 
 ```ruby
-UnitMeasurements::Length.new(1, "km") == UnitMeasurements::Length.new(1, "km")
-#=> true
-UnitMeasurements::Length.parse("1 km") <= UnitMeasurements::Length.parse("0.5 km")
-#=> false
-UnitMeasurements::Length.new(1, "ft").between?(UnitMeasurements::Length.new(12, "in"), UnitMeasurements::Length.new(24, "in"))
+UnitMeasurements::Length.parse("1 km") != UnitMeasurements::Length.parse("1 m")
 #=> true
 ```
 
+You can check supported comparisons along with their examples
+[here](https://shivam091.github.io/unit_measurements/UnitMeasurements/Comparison.html).
+
 ### Arithmetic
 
 You have ability to perform arithmetic operations on measurements with the same or
 different units within a same unit group. You can perform arithmetic operations on
-measurement by either other measurement with compatible unit or number.
-In cases of different units, the left hand side takes precedence:
-
-**Methods:**
-1. `#+` - Adds the other measurement quantity or number to the measurement.
-2. `#-` - Subtracts the other measurement quantity or number from the measurement.
-3. `#*` - Multiplies the measurement quantity by other measurement quantity or number.
-4. `#/` - Divides the measurement quantity by other measurement quantity or number.
+measurement by either other measurement with compatible unit or numeric value.
+In cases of different units, the left hand side takes precedence.
 
 ```ruby
 UnitMeasurements::Length.new(1, "km") + UnitMeasurements::Length.new(1, "m")
 #=> 1.001 km
-UnitMeasurements::Length.new(2, "km") - 1
-#=> 1 km
-UnitMeasurements::Length.new(2, "km") * 2
-#=> 4 km
-UnitMeasurements::Length.new(4, "km") / UnitMeasurements::Length.new(2, "km")
-#=> 2 km
+UnitMeasurements::Length.new(2, "km") * 2+2i
+#=> 4+2i km
 ```
 
-### Math
+You can check supported arithmetic operations along with their examples
+[here](https://shivam091.github.io/unit_measurements/UnitMeasurements/Arithmetic.html).
 
-You can perform mathematical operations on the measurements.
+### Math
 
-**Methods:**
-1. `#round` - Rounds quantity of the measurement. If `ndigits` is not specified, quantity is rounded to `Integer`.
-2. `#abs` - Returns absolute value of the measurement quantity.
-3. `#floor` - Rounds quantity of the measurement to next lower integer.
-4. `#ceil` - Rounds quantity of the measurement to next higher integer.
+You can perform mathematical functions on the measurements.
 
 ```ruby
-UnitMeasurements::Length.new(1, "m").to("in").round(4)
-#=> 39.3701 in
-UnitMeasurements::Length.new(-17.625, "m").abs
-#=> 17.625 m
-UnitMeasurements::Length.new(17.625, "m").floor
-#=> 17 m
-UnitMeasurements::Length.new(17.625, "m").ceil
-#=> 18 m
+UnitMeasurements::Length.new(17.625, "m").round
+#   => 18 m
 ```
 
+You can check supported mathematical functions along with their examples
+[here](https://shivam091.github.io/unit_measurements/UnitMeasurements/Math.html).
+
 ### Conversions
 
 You can convert measurement quantity directly to other numeric types viz.
@@ -329,16 +300,11 @@ You can convert measurement quantity directly to other numeric types viz.
 ```ruby
 UnitMeasurements::Length.new(2.25567, "km").to_i
 #=> 2 km
-UnitMeasurements::Length.new(2.25567, "km").to_f
-#=> 2.25567 km
-UnitMeasurements::Length.new(2.25567, "km").to_r
-#=> 225567/100000 km
-UnitMeasurements::Length.new(2.25567, "km").to_d
-#=> 2.25567 km
-UnitMeasurements::Length.new(2.25567, "km").to_c
-#=> 2.25567+0i km
 ```
 
+You can check more about them along with their examples
+[here](https://shivam091.github.io/unit_measurements/UnitMeasurements/Conversion.html).
+
 ## Units
 
 The **`UnitMeasurements::Unit`** class is used to represent the units for a measurement.
@@ -377,7 +343,8 @@ Units declared through it will have automatic support for all decimal prefixes:
 
 ### Bundled units
 
-There are tons of units that are bundled in `unit_measurements`. You can check them out [here](units.md).
+There are tons of units that are bundled in `unit_measurements`. You can check them out
+[here](https://github.com/shivam091/unit_measurements/blob/main/units.md).
 
 ### Specifing units
 
@@ -464,4 +431,4 @@ Volume = UnitMeasurements::Volume
 
 ## License
 
-Copyright 2023 [Harshal V. LADHE](https://github.com/shivam091), Released under the [MIT License](http://opensource.org/licenses/MIT).
+Copyright 2023 [Harshal V. LADHE]((https://shivam091.github.io)), Released under the [MIT License](http://opensource.org/licenses/MIT).

data/lib/unit_measurements/arithmetic.rb

@@ -3,61 +3,118 @@
 # -*- warn_indent: true -*-
 
 module UnitMeasurements
+  # The +UnitMeasurements::Arithmetic+ mixin module provides methods for
+  # performing arithmetic operations (addition, subtraction, multiplication,
+  # division, etc) on measurements of the same unit group. In case the
+  # measurements represents different units, the left hand side takes precedence
+  # while performing the arithmetic operation on them.
+  #
+  # This module is included in the +Measurement+ class to allow arithmetic
+  # operations on the measurements.
+  #
+  # @see Measurement
+  # @author {Harshal V. Ladhe}[https://shivam091.github.io/]
+  # @since 1.4.0
   module Arithmetic
-    # Adds the other measurement quantity or number to the measurement.
+    # Adds the quantity of the other measurement or a numeric value to the
+    # quantity of the current measurement.
     #
-    # @param [Numeric or Measurement] other
+    # @param [Numeric|Measurement] other
+    #   The value to be added. It can be a numeric value or another measurement.
     #
     # @example
-    #   UnitMeasurements::Weight.new(1, "kg") + UnitMeasurements::Weight.new(1, "g")
-    #   => 1.001 kg
+    #   UnitMeasurements::Length.new(1, "km") + UnitMeasurements::Length.new(1, "m")
+    #   => 1.001 km
     #
-    # @return [Measurement]
+    #   UnitMeasurements::Length.new(1, "km") + 4.5
+    #   => 5.5 km
+    #
+    # @return [Measurement] A new +Measurement+ instance with the combined quantity.
+    #
+    # @author {Harshal V. Ladhe}[https://shivam091.github.io/]
+    # @since 1.4.0
     def +(other)
       arithmetic_operation(other, :+)
     end
 
-    # Subtracts the other measurement quantity or number from the measurement.
+    # Subtracts the quantity of the other measurement or a numeric value from the
+    # quantity of the current measurement.
     #
-    # @param [Numeric or Measurement] other
+    # @param [Numeric|Measurement] other
+    #   The value to be subtracted. It can be a numeric value or another measurement.
     #
     # @example
-    #   UnitMeasurements::Weight.new(2, "kg") - 1
-    #   => 1 kg
+    #   UnitMeasurements::Length.new(1, "km") - UnitMeasurements::Length.new(2, "in")
+    #   => 0.9999492 km
     #
-    # @return [Measurement]
+    #   UnitMeasurements::Length.new(2, "km") - 1e+2
+    #   => -98.0 km
+    #
+    # @return [Measurement] A new +Measurement+ instance with the subtracted quantity.
+    #
+    # @author {Harshal V. Ladhe}[https://shivam091.github.io/]
+    # @since 1.4.0
     def -(other)
       arithmetic_operation(other, :-)
     end
 
-    # Multiplies the measurement quantity by other measurement quantity or number.
+    # Multiplies the quantity of the current measurement by the quantity of the
+    # other measurement or a numeric value.
     #
-    # @param [Numeric or Measurement] other
+    # @param [Numeric|Measurement] other
+    #   The value to be multiplied. It can be a numeric value or another measurement.
     #
     # @example
-    #   UnitMeasurements::Weight.new(2, "kg") * 2
-    #   => 4 kg
+    #   UnitMeasurements::Length.new(2, "km") * UnitMeasurements::Length.new(3, "in")
+    #   => 0.0001524 km
     #
-    # @return [Measurement]
+    #   UnitMeasurements::Length.new(2, "km") * 2+2i
+    #   => 4+2i km
+    #
+    # @return [Measurement] A new +Measurement+ instance with the multiplied quantity.
+    #
+    # @author {Harshal V. Ladhe}[https://shivam091.github.io/]
+    # @since 1.4.0
     def *(other)
       arithmetic_operation(other, :*)
     end
 
-    # Divides the measurement quantity by other measurement quantity or number.
+    # Divides the quantity of the current measurement by the quantity of the other
+    # measurement or a numeric value.
     #
-    # @param [Numeric or Measurement] other
+    # @param [Numeric|Measurement] other
+    #   The value to be divided. It can be a numeric value or another measurement.
     #
     # @example
-    #   UnitMeasurements::Weight.new(4, "kg") / UnitMeasurements::Weight.new(2, "kg")
-    #   => 2 kg
+    #   UnitMeasurements::Length.new(4, "km") / UnitMeasurements::Length.new(2, "km")
+    #   => 2 km
     #
-    # @return [Measurement]
+    #   UnitMeasurements::Length.new(2, "km") / 2
+    #   => 1 km
+    #
+    # @return [Measurement] A new +Measurement+ instance with the divided quantity.
+    #
+    # @author {Harshal V. Ladhe}[https://shivam091.github.io/]
+    # @since 1.4.0
     def /(other)
       arithmetic_operation(other, :/)
     end
 
     private
 
+    # @private
+    # Coerces a numeric value or another measurement for arithmetic operations.
+    #
+    # @param [Numeric|Measurement] other
+    #   The value to be coerced. It can be a numeric value or another measurement.
+    #
+    # @return [Array<Measurement>] An array containing the coerced values.
+    #
+    # @raise [TypeError]
+    #   If the coercion is not possible due to incompatible types.
+    #
+    # @author {Harshal V. Ladhe}[https://shivam091.github.io/]
+    # @since 1.4.0
     def coerce(other)
       case other
       when Numeric    then [self.class.new(other, self.unit), self]
@@ -66,6 +123,20 @@ module UnitMeasurements
       end
     end
 
+    # @private
+    # Performs an arithmetic operation (addition, subtraction, multiplication,
+    # or division) on the current measurement and another numeric value.
+    #
+    # @param [Numeric|Measurement] other
+    #   The value to be used in the arithmetic operation. It can be a numeric value
+    #   or another measurement.
+    # @param [Symbol] operator The operator to be used for the operation.
+    #
+    # @return [Measurement]
+    #   A new +Measurement+ instance with the result of the arithmetic operation.
+    #
+    # @author {Harshal V. Ladhe}[https://shivam091.github.io/]
+    # @since 1.4.0
     def arithmetic_operation(other, operator)
       other, _ = coerce(other)
 

data/lib/unit_measurements/base.rb

@@ -7,6 +7,61 @@ require "unit_measurements/version"
 
 module UnitMeasurements
   class << self
+    # Creates a new unit group based on the provided +block+ of instructions.
+    #
+    # The +build+ method allows you to define and create a custom unit group with
+    # units and their conversions. It takes a block of instructions as an argument,
+    # which is evaluated by an instance of +UnitGroupBuilder+.
+    #
+    # Within the +block+, you can use various methods provided by +UnitGroupBuilder+
+    # to define units, group them into unit system, and set primitive unit of
+    # the unit group. These methods include +primitive+, +system+, +si_unit+,
+    # and +unit+.
+    #
+    # The resulting unit group is encapsulated in a new subclass of +Measurement+.
+    # This subclass will have access to the defined units and their conversions
+    # through the +unit_group+ class attribute.
+    #
+    # This method provides a powerful way to create specialized unit groups tailored
+    # to specific measurement domains.
+    #
+    # @example
+    #   UnitMeasurements.build do
+    #     primitive "m"
+    #
+    #     system :metric do
+    #       si_unit "m", aliases: ["meter", "metre", "meters", "metres"]
+    #     end
+    #
+    #     system :imperial do
+    #       unit "in", value: "25.4 mm", aliases: ['"', "inch", "inches"]
+    #     end
+    #   end
+    #
+    # @param block
+    #   A block of instructions for defining units and their conversions within
+    #   the unit group.
+    #
+    # @yield [builder]
+    #   A block that defines the units to be added to the unit group.
+    #   The block takes a {UnitGroupBuilder} instance as a parameter.
+    #
+    # @yieldparam builder [UnitGroupBuilder]
+    #   The {UnitGroupBuilder} instance to define units within the unit group.
+    #
+    # @yieldreturn [UnitGroup]
+    #   Returns an instance of {UnitGroup} containing the units and their conversions
+    #   defined within the block.
+    #
+    # @return [Class]
+    #   A new subclass of +Measurement+ with the defined units and conversions.
+    #
+    # @see Unit
+    # @see UnitGroup
+    # @see UnitGroupBuilder
+    # @see Measurement
+    # @author {Harshal V. Ladhe}[https://shivam091.github.io/]
+    # @since 1.0.0
     def build(&block)
       builder = UnitGroupBuilder.new
       builder.instance_eval(&block)
@@ -22,6 +77,7 @@ module UnitMeasurements
   end
 end
 
+# The following requires load various components of the unit measurements library.
 require "unit_measurements/unit_group_builder"
 require "unit_measurements/unit"
 require "unit_measurements/unit_group"

data/lib/unit_measurements/comparison.rb

@@ -3,17 +3,58 @@
 # -*- warn_indent: true -*-
 
 module UnitMeasurements
+  # The +UnitMeasurements::Comparison+ mixin module is included in measurement
+  # classes to enable comparison operations (e.g., less than, equal to, greater
+  # than, etc.) between two measurements of the same unit group.
+  #
+  # This module is included in the +Measurement+ class to allow comparison of two
+  # measurements.
+  #
+  # @see Measurement
+  # @author {Harshal V. Ladhe}[https://shivam091.github.io/]
+  # @since 1.3.0
   module Comparison
     include Comparable
 
-    # Implements +Comparable+ methods on the quantities of two measurements of
-    # the same unit group.
+    # This method is used to compare the quantity of two measurements. It
+    # implements the comparison logic based on the +<=>+ method defined in the
+    # +Comparable+ module.
     #
     # @example
-    #   UnitMeasurements::Weight.new(1, "kg") == UnitMeasurements::Weight.new(1, :kg)
+    #   UnitMeasurements::Length.new(1, "km") == UnitMeasurements::Length.new(1, :km)
     #   => true
     #
-    # @return [Boolean]
+    #   UnitMeasurements::Length.parse("1 km") == UnitMeasurements::Length.parse("1000 m")
+    #   => true
+    #
+    #   UnitMeasurements::Length.parse("1 km") != UnitMeasurements::Length.parse("1 m")
+    #   => true
+    #
+    #   UnitMeasurements::Length.parse("1 km") < UnitMeasurements::Length.parse("0.5 km")
+    #   => false
+    #
+    #   UnitMeasurements::Length.parse("1 km") > UnitMeasurements::Length.parse("0.5 km")
+    #   => true
+    #
+    #   UnitMeasurements::Length.parse("1 km") <= UnitMeasurements::Length.parse("0.5 km")
+    #   => false
+    #
+    #   UnitMeasurements::Length.parse("1 km") >= UnitMeasurements::Length.parse("0.5 km")
+    #   => true
+    #
+    #   UnitMeasurements::Length.new(1, "ft").between?(UnitMeasurements::Length.new(12, "in"), UnitMeasurements::Length.new(24, "in"))
+    #   => true
+    #
+    # @param [Measurement] object The measurement instance to compare with.
+    #
+    # @return
+    #   +nil+ if the comparison is not possible (e.g., if the +object+ is not of
+    #   the same unit group). A negative integer if +self+ is less than +object+.
+    #   +Zero+ if self is equal to +object+. A positive integer if +self+ is
+    #   greater than +object+.
+    #
+    # @author {Harshal V. Ladhe}[https://shivam091.github.io/]
+    # @since 1.3.0
     def <=>(object)
       return nil unless object.is_a?(self.class)