[DOC] Doc for Integer#floor (#11077)

BurdetteLamar · web-flow · commit f5dfadf38bf1 · 2024-07-03T16:00:00.000-04:00
diff --git a/numeric.c b/numeric.c
@@ -5695,24 +5695,56 @@ int_round(int argc, VALUE* argv, VALUE num)
 }
 
 /*
+ *  :markup: markdown
+ *
  *  call-seq:
  *    floor(ndigits = 0) -> integer
  *
- *  Returns the largest number less than or equal to +self+ with
- *  a precision of +ndigits+ decimal digits.
+ *  Returns an integer that is a "floor" value for `self`,
+ *  as specified by the given `ndigits`,
+ *  which must be an
+ *  [integer-convertible object](rdoc-ref:implicit_conversion.rdoc@Integer-Convertible+Objects).
  *
- *  When +ndigits+ is negative, the returned value
- *  has at least <tt>ndigits.abs</tt> trailing zeros:
+ *  - When `self` is zero, returns zero (regardless of the value of `ndigits`):
  *
- *    555.floor(-1)  # => 550
- *    555.floor(-2)  # => 500
- *    -555.floor(-2) # => -600
- *    555.floor(-3)  # => 0
+ *      ```
+ *      0.floor(2)  # => 0
+ *      0.floor(-2) # => 0
+ *      ```
  *
- *  Returns +self+ when +ndigits+ is zero or positive.
+ *  - When `self` is non-zero and `ndigits` is non-negative, returns `self`:
+ *
+ *      ```
+ *      555.floor     # => 555
+ *      555.floor(50) # => 555
+ *      ```
+ *
+ *  - When `self` is non-zero and `ndigits` is negative,
+ *    returns a value based on a computed granularity:
+ *
+ *      - The granularity is <tt>ndigits.abs * 10</tt>.
+ *      - The returned value is the largest multiple of the granularity
+ *        that is less than or equal to `self`.
+ *
+ *      Examples with positive `self`:
+ *
+ *      | ndigits | Granularity | 1234.floor(ndigits) |
+ *      |--------:|------------:|--------------------:|
+ *      | -1      | 10          | 1230                |
+ *      | -2      | 100         | 1200                |
+ *      | -3      | 1000        | 1000                |
+ *      | -4      | 10000       | 0                   |
+ *      | -5      | 100000      | 0                   |
+ *
+ *      Examples with negative `self`:
  *
- *    555.floor     # => 555
- *    555.floor(50) # => 555
+ *      | ndigits | Granularity | -1234.floor(ndigits) |
+ *      |--------:|------------:|---------------------:|
+ *      | -1      | 10          | -1240                |
+ *      | -2      | 100         | -1300                |
+ *      | -3      | 1000        | -2000                |
+ *      | -4      | 10000       | -10000               |
+ *      | -5      | 100000      | -100000              |
  *
  *  Related: Integer#ceil.
  *
