Project

General

Profile

Bug #13262

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

Added by stomar (Marcus Stollsteimer) over 2 years ago. Updated over 2 years ago.

Status:
Closed
Priority:
Normal
Assignee:
-
Target version:
-
[ruby-core:79815]

Description

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:

History

Updated by stomar (Marcus Stollsteimer) over 2 years ago

  • Description updated (diff)

Updated by shevegen (Robert A. Heiler) over 2 years ago

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

May I ask how you did discover this?

Updated by stomar (Marcus Stollsteimer) over 2 years ago

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.

Updated by stomar (Marcus Stollsteimer) over 2 years ago

  • Status changed from Open to Closed

Closing. Fixed with r58432 (removing of mathn).

Also available in: Atom PDF