Bug #13262: Docs of core classes (Math and others) are shadowed by mathn.rb docs

• Status: Closed
• Assignee: -
• Target version: -
• Backport: 2.2: UNKNOWN, 2.3: UNKNOWN, 2.4: UNKNOWN

[stomar (Marcus Stollsteimer)]

The deprecated (#10169) mathn library leaks documentation into some core classes, or even replaces it (see example further down).

I would like to fix this, but I could need some ideas what would be the best way to do that. The problem is that mathn is not a module/class which could have it's own docs, but only modifies core classes.

Should I:

• simply comment out the rdoc?
• add sections/paragraphs directly to the affected core classes, at the appropriate place?
• can ri mathn be made to work somehow (documentation for a source file)?
• ...?

Example: Math.sqrt

$ ri Math::sqrt

(from ruby site)
------------------------------------------------------------------------------
  sqrt(a)

------------------------------------------------------------------------------

Computes the square root of a.  It makes use of Complex and Rational to
have no rounding errors if possible.

  Math.sqrt(4/9)      # => 2/3
  Math.sqrt(- 4/9)    # => Complex(0, 2/3)
  Math.sqrt(4.0/9.0)  # => 0.666666666666667

That's not the standard behavior of Math.sqrt and neither the documentation that is provided in math.c; these are the docs provided in lib/mathn.rb, corresponding to the behavior after require "mathn".

Also affected:

• class documentation of Integer (mathn docs are added at some unspecified place before the proper docs, https://docs.ruby-lang.org/en/trunk/Integer.html)
• ditto for Math (https://docs.ruby-lang.org/en/trunk/Math.html)
• ditto for Object (shows the general description of mathn: https://docs.ruby-lang.org/en/trunk/Object.html#method-i-unknown-label-mathn)
• internal Math.rsqrt method documented publicly (r57744)

[stomar (Marcus Stollsteimer)]

• Description updated (diff)

[shevegen (Robert A. Heiler)]

Very interesting find. I would not have thought that this is a possibility.

May I ask how you did discover this?

[stomar (Marcus Stollsteimer)]

I first stumbled upon it when doing ri Integer (before the proper documentation there appear snippets introduced by BigDecimal, OpenSSL (both fixed upstream now), and mathn), and then also noticed in the context of #13219 that ri Math.sqrt does not match the actual behavior.

[stomar (Marcus Stollsteimer)]

• Status changed from Open to Closed

Closing. Fixed with r58432 (removing of mathn).