Issue #13262 has been reported by Marcus Stollsteimer.

----------------------------------------
Bug #13262: Docs of core classes (Math and others) are shadowed by mathn.rb docs
https://bugs.ruby-lang.org/issues/13262

* Author: Marcus Stollsteimer
* Status: Open
* Priority: Normal
* Assignee: 
* Target version: 
* ruby -v: 
* Backport: 2.2: UNKNOWN, 2.3: UNKNOWN, 2.4: UNKNOWN
----------------------------------------
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




-- 
https://bugs.ruby-lang.org/

Unsubscribe: <mailto:ruby-core-request / ruby-lang.org?subject=unsubscribe>
<http://lists.ruby-lang.org/cgi-bin/mailman/options/ruby-core>