Enhanced RDoc for numeric.c (#5184)

Adds remarks about literals and Kernel methods to Float and Integer.

2 files changed, 26 insertions, 12 deletions

diff --git a/doc/syntax/literals.rdoc b/doc/syntax/literals.rdoc
index cfdbb71700..b663f27816 100644
--- a/doc/syntax/literals.rdoc
+++ b/doc/syntax/literals.rdoc
@@ -22,6 +22,8 @@ true value in conditional expressions.
 
 == Numbers
 
+=== \Integer Literals
+
 You can write integers of any size as follows:
 
   1234
@@ -31,15 +33,6 @@ These numbers have the same value, 1,234.  The underscore may be used to
 enhance readability for humans.  You may place an underscore anywhere in the
 number.
 
-Floating point numbers may be written as follows:
-
-  12.34
-  1234e-2
-  1.234E1
-
-These numbers have the same value, 12.34.  You may use underscores in floating
-point numbers as well.
-
 You can use a special prefix to write numbers in decimal, hexadecimal, octal
 or binary formats.  For decimal numbers use a prefix of <tt>0d</tt>, for
 hexadecimal numbers use a prefix of <tt>0x</tt>, for octal numbers use a
@@ -68,7 +61,18 @@ Examples:
 All these numbers have the same decimal value, 170.  Like integers and floats
 you may use an underscore for readability.
 
-=== Rational numbers
+=== Floating-Point Literals
+
+Floating-point numbers may be written as follows:
+
+  12.34
+  1234e-2
+  1.234E1
+
+These numbers have the same value, 12.34.  You may use underscores in floating
+point numbers as well.
+
+=== Rational Numbers
 
 Numbers suffixed by +r+ are Rational numbers.
 
diff --git a/numeric.c b/numeric.c
index c15131cc1c..4492af5bb3 100644
--- a/numeric.c
+++ b/numeric.c
@@ -934,9 +934,9 @@ num_negative_p(VALUE num)
 
 /********************************************************************
  *
- * Document-class: Float
+ *  Document-class: Float
  *
- *  Float objects represent inexact real numbers using the native
+ *  A \Float object represents a sometimes-inexact real number using the native
  *  architecture's double-precision floating point representation.
  *
  *  Floating point has a different arithmetic and is an inexact number.
@@ -946,6 +946,11 @@ num_negative_p(VALUE num)
  *  - https://github.com/rdp/ruby_tutorials_core/wiki/Ruby-Talk-FAQ#floats_imprecise
  *  - https://en.wikipedia.org/wiki/Floating_point#Accuracy_problems
  *
+ *  You can create a \Float object explicitly with:
+ *
+ *  - Global method {Float}[Kernel.html#method-i-Float].
+ *  - A {floating-point literal}[doc/syntax/literals_rdoc.html#label-Floating-Point+Literals].
+ *
  *  == What's Here
  *
  *  First, what's elsewhere. \Class \Float:
@@ -3472,6 +3477,11 @@ rb_num2ull(VALUE val)
  *
  * An \Integer object represents an integer value.
  *
+ * You can create an \Integer object explicitly with:
+ *
+ * - Global method {Integer}[Kernel.html#method-i-Integer].
+ * - An {integer literal}[doc/syntax/literals_rdoc.html#label-Integer+Literals].
+ *
  * An attempt to add a singleton method to an instance of this class
  * causes an exception to be raised.
  *