Update documentation and fix typos (#376)

* Update documentation for unit methods

* Fix typo in format description in string_spec.rb

Author: olbrich

README.md

@@ -81,11 +81,15 @@ Unit#*()      # Multiply.
 Unit#/()      # Divide.
 Unit#**()     # Exponentiate.  Exponent must be an integer, can be positive,  negative, or zero
 Unit#inverse  # Returns 1/unit
-Unit#abs      # Returns absolute value of the unit quantity.  Strips off the  units
+Unit#abs      # Returns absolute value of the unit quantity.  Units are preserved
 Unit#ceil     # rounds quantity to next highest integer
 Unit#floor    # rounds quantity down to next lower integer
 Unit#round    # rounds quantity to nearest integer
+Unit#truncate # truncates quantity to an integer
 Unit#to_int   # returns the quantity as an integer
+Unit#divmod   # divide and return quotient and remainder
+Unit#remainder# returns remainder of division
+Unit#quo      # returns quotient as a float or complex
 ```
 
 Unit will coerce other objects into a Unit if used in a formula. This means...
@@ -260,6 +264,8 @@ end
 2. `base_scalar` will return the scalar in base units (SI)
 3. `units` will return the name of the units (without the scalar)
 4. `base` will return the unit converted to base units (SI)
+5. `best_prefix` will return a new unit scaled with an appropriate prefix for
+   human readability (e.g., '1000 m' becomes '1 km')
 
 ### Storing in a database
 

lib/ruby_units/date.rb

@@ -45,7 +45,9 @@ def to_unit(other = nil)
       other ? RubyUnits::Unit.new(self).convert_to(other) : RubyUnits::Unit.new(self)
     end
 
-    # @deprecated
+    # @deprecated The dump parameter is deprecated and will be removed in a future version.
+    # @param dump [Boolean] if true, use default inspect; if false, use to_s (deprecated behavior)
+    # @return [String]
     def inspect(dump = false)
       dump ? super : to_s
     end

lib/ruby_units/unit.rb

@@ -727,7 +727,8 @@ def to_s(target_units = nil, precision: 0.0001, format: RubyUnits.configuration.
     end
 
     # Normally pretty prints the unit, but if you really want to see the guts of it, pass ':dump'
-    # @deprecated
+    # @deprecated The dump parameter is deprecated. Use the default inspect behavior for debugging.
+    # @param dump [Symbol, nil] pass :dump to see internal structure (deprecated)
     # @return [String]
     def inspect(dump = nil)
       return super() if dump
@@ -1014,8 +1015,11 @@ def %(other)
     end
     alias modulo %
 
-    # @param [Object] other
-    # @return [Unit]
+    # Divide two units and return quotient as a float or complex.
+    # Similar to division but ensures floating point result.
+    #
+    # @param other [Numeric, Unit]
+    # @return [Float, Complex, Unit]
     # @raise [ZeroDivisionError] if other is zero
     def quo(other)
       self / other
@@ -1063,8 +1067,10 @@ def **(other)
       end
     end
 
-    # returns the unit raised to the n-th power
-    # @param [Integer] n
+    # Raise a unit to a power.
+    # Returns the unit raised to the n-th power.
+    #
+    # @param n [Integer] the exponent (must be an integer)
     # @return [Unit]
     # @raise [ArgumentError] when attempting to raise a temperature to a power
     # @raise [ArgumentError] when n is not an integer
@@ -1080,8 +1086,10 @@ def power(n)
     end
 
     # Calculates the n-th root of a unit
-    # if n < 0, returns 1/unit^(1/n)
-    # @param [Integer] n
+    # Returns the nth root of a unit.
+    # If n < 0, returns 1/unit^(1/n)
+    #
+    # @param n [Integer] the root degree (must be an integer, cannot be 0)
     # @return [Unit]
     # @raise [ArgumentError] when attempting to take the root of a temperature
     # @raise [ArgumentError] when n is not an integer
@@ -1267,9 +1275,9 @@ def as_json(*)
 
     # Returns the 'unit' part of the Unit object without the scalar
     #
-    # @param with_prefix [Boolean] include prefixes in output
-    # @param format [Symbol] Set to :exponential to force all units to be displayed in exponential format
-    #
+    # @param with_prefix [Boolean] include prefixes in output (default: true)
+    # @param format [Symbol] Set to :exponential to force exponential notation (e.g., 'm*s^-2'),
+    #   or :rational for rational notation (e.g., 'm/s^2'). Defaults to configuration setting.
     # @return [String]
     def units(with_prefix: true, format: nil)
       return "" if @numerator == UNITY_ARRAY && @denominator == UNITY_ARRAY
@@ -1367,8 +1375,11 @@ def truncate(*args)
       self.class.new(@scalar.truncate(*args), @numerator, @denominator)
     end
 
-    # returns next unit in a range.  '1 mm'.to_unit.succ #=> '2 mm'.to_unit
-    # only works when the scalar is an integer
+    # Returns next unit in a range. Increments the scalar by 1.
+    # Only works when the scalar is an integer.
+    # This is used primarily to make ranges work.
+    #
+    # @example '1 mm'.to_unit.succ #=> '2 mm'.to_unit
     # @return [Unit]
     # @raise [ArgumentError] when scalar is not equal to an integer
     def succ
@@ -1379,8 +1390,11 @@ def succ
 
     alias next succ
 
-    # returns previous unit in a range.  '2 mm'.to_unit.pred #=> '1 mm'.to_unit
-    # only works when the scalar is an integer
+    # Returns previous unit in a range. Decrements the scalar by 1.
+    # Only works when the scalar is an integer.
+    # This is used primarily to make ranges work.
+    #
+    # @example '2 mm'.to_unit.pred #=> '1 mm'.to_unit
     # @return [Unit]
     # @raise [ArgumentError] when scalar is not equal to an integer
     def pred
@@ -1416,13 +1430,22 @@ def zero?
     end
 
     # @example '5 min'.to_unit.ago
-    # @return [Unit]
+    # Returns the time that was this duration ago from now.
+    # Alias for #before with default time of Time.now
+    #
+    # @example '5 min'.to_unit.ago #=> Time 5 minutes ago
+    # @return [Time, DateTime]
     def ago
       before
     end
 
-    # @example '5 min'.before(time)
-    # @return [Unit]
+    # Returns the time that was this duration before the given time point.
+    #
+    # @example '5 min'.to_unit.before(time) #=> Time 5 minutes before time
+    # @example '5 min'.to_unit.before #=> Time 5 minutes ago
+    # @param time_point [Time, Date, DateTime] the reference time (defaults to Time.now)
+    # @return [Time, Date, DateTime]
+    # @raise [ArgumentError] when time_point is not a Time, Date, or DateTime
     def before(time_point = ::Time.now)
       case time_point
       when Time, Date, DateTime
@@ -1506,6 +1529,10 @@ def coerce(other)
     # * Units containing 'kg' will be returned as is. The prefix in 'kg' makes this an odd case.
     # * It will use `centi` instead of `milli` when the scalar is between 0.01 and 0.001
     #
+    # @example
+    #   Unit.new('1000 m').best_prefix  #=> '1 km'.to_unit
+    #   Unit.new('0.5 m').best_prefix   #=> '50 cm'.to_unit
+    #   Unit.new('1500 W').best_prefix  #=> '1.5 kW'.to_unit
     # @return [Unit]
     def best_prefix
       return to_base if scalar.zero?

spec/ruby_units/string_spec.rb

@@ -8,7 +8,7 @@
     specify { expect("1 m".convert_to("ft")).to be_within(RubyUnits::Unit.new("0.01 ft")).of RubyUnits::Unit.new("3.28084 ft") }
   end
 
-  describe "% (format)S" do
+  describe "% (format)" do
     subject(:unit) { RubyUnits::Unit.new("1.23456 m/s^2") }
 
     specify { expect("%0.2f" % 1.23).to eq("1.23") }