Adding links to literals and Kernel (#5192)

* Adding links to literals and Kernel

array.c

@@ -7843,13 +7843,20 @@ rb_ary_deconstruct(VALUE ary)
  *
  *  == Creating Arrays
  *
- *  A new array can be created by using the literal constructor
+ *  You can create an \Array object explicitly with:
- *  <code>[]</code>.  Arrays can contain different types of objects.  For
+ *
+ *  - An {array literal}[doc/syntax/literals_rdoc.html#label-Array+Literals].
+ *
+ *  You can convert certain objects to Arrays with:
+ *
+ *  - \Method {Array}[Kernel.html#method-i-Array].
+ *
+ *  An \Array can contain different types of objects.  For
  *  example, the array below contains an Integer, a String and a Float:
  *
  *     ary = [1, "two", 3.0] #=> [1, "two", 3.0]
  *
- *  An array can also be created by explicitly calling Array.new with zero, one
+ *  An array can also be created by calling Array.new with zero, one
  *  (the initial size of the Array) or two arguments (the initial size and a
  *  default object).
  *

complex.c

@@ -2267,6 +2267,14 @@ float_arg(VALUE self)
  * and i is imaginary unit.  Real a equals complex a+0i
  * mathematically.
  *
+ * You can create a \Complex object explicitly with:
+ *
+ * - A {complex literal}[doc/syntax/literals_rdoc.html#label-Complex+Literals].
+ *
+ * You can convert certain objects to \Complex objects with:
+ *
+ * - \Method {Complex}[Kernel.html#method-i-Complex].
+ *
  * Complex object can be created as literal, and also by using
  * Kernel#Complex, Complex::rect, Complex::polar or to_c method.
  *

doc/syntax/literals.rdoc

@@ -9,10 +9,10 @@ Literals create objects you can use in your program.  Literals include:
 * Arrays
 * Hashes
 * Ranges
-* Regular Expressions
+* Regexps
-* Procs
+* Lambda Procs
 
-== Booleans and nil
+== Boolean and Nil Literals
 
 +nil+ and +false+ are both false values.  +nil+ is sometimes used to indicate
 "no value" or "unknown" but evaluates to +false+ in conditional expressions.
@@ -61,7 +61,7 @@ Examples:
 All these numbers have the same decimal value, 170.  Like integers and floats
 you may use an underscore for readability.
 
-=== Floating-Point Literals
+=== \Float Literals
 
 Floating-point numbers may be written as follows:
 
@@ -72,35 +72,37 @@ Floating-point numbers may be written as follows:
 These numbers have the same value, 12.34.  You may use underscores in floating
 point numbers as well.
 
-=== Rational Numbers
+=== \Rational Literals
 
-Numbers suffixed by +r+ are Rational numbers.
+You can write a Rational number as follows (suffixed +r+):
 
   12r         #=> (12/1)
   12.3r       #=> (123/10)
 
-Rational numbers are exact, whereas Float numbers are inexact.
+A \Rational number is exact, whereas a \Float number may be inexact.
 
   0.1r + 0.2r #=> (3/10)
   0.1 + 0.2   #=> 0.30000000000000004
 
-=== Complex numbers
+=== \Complex Literals
 
-Numbers suffixed by +i+ are Complex (or imaginary) numbers.
+You can write a Complex number as follows (suffixed +i+):
 
   1i          #=> (0+1i)
   1i * 1i     #=> (-1+0i)
 
-Also Rational numbers may be imaginary numbers.
+Also \Rational numbers may be imaginary numbers.
 
   12.3ri      #=> (0+(123/10)*i)
 
-+i+ must be placed after +r+, the opposite is not allowed.
++i+ must be placed after +r+; the opposite is not allowed.
 
-  12.3ir      #=> syntax error
+  12.3ir      #=> Syntax error
 
 == Strings
 
+=== \String Literals
+
 The most common way of writing strings is using <tt>"</tt>:
 
   "This is a string."
@@ -198,7 +200,7 @@ a single codepoint in the script encoding:
   ?\C-\M-a #=> "\x81", same as above
   ?あ      #=> "あ"
 
-=== Here Documents (heredocs)
+=== Here Document Literals
 
 If you are writing a large block of text you may use a "here document" or
 "heredoc":
@@ -278,7 +280,7 @@ read:
   content for heredoc two
   TWO
 
-== Symbols
+== \Symbol Literals
 
 A Symbol represents a name inside the ruby interpreter.  See Symbol for more
 details on what symbols are and when ruby creates them internally.
@@ -297,7 +299,7 @@ Like strings, a single-quote may be used to disable interpolation:
 When creating a Hash, there is a special syntax for referencing a Symbol as
 well.
 
-== Arrays
+== \Array Literals
 
 An array is created using the objects between <tt>[</tt> and <tt>]</tt>:
 
@@ -310,7 +312,7 @@ You may place expressions inside the array:
 
 See Array for the methods you may use with an array.
 
-== Hashes
+== \Hash Literals
 
 A hash is created using key-value pairs between <tt>{</tt> and <tt>}</tt>:
 
@@ -334,7 +336,7 @@ is equal to
 
 See Hash for the methods you may use with a hash.
 
-== Ranges
+== \Range Literals
 
 A range represents an interval of values.  The range may include or exclude
 its ending value.
@@ -347,7 +349,7 @@ its ending value.
 You may create a range of any object.  See the Range documentation for details
 on the methods you need to implement.
 
-== Regular Expressions
+== \Regexp Literals
 
 A regular expression is created using "/":
 
@@ -365,7 +367,7 @@ characters than a string.
 
 See Regexp for a description of the syntax of regular expressions.
 
-== Procs
+== Lambda Proc Literals
 
 A lambda proc can be created with <tt>-></tt>:
 
@@ -379,13 +381,13 @@ You can require arguments for the proc as follows:
 
 This proc will add one to its argument.
 
-== Percent Strings
+== Percent Literals
 
 Besides <tt>%(...)</tt> which creates a String, the <tt>%</tt> may create
 other types of object.  As with strings, an uppercase letter allows
 interpolation and escaped characters while a lowercase letter disables them.
 
-These are the types of percent strings in ruby:
+These are the types of percent literals:
 
 <tt>%i</tt> :: Array of Symbols
 <tt>%q</tt> :: String

hash.c

@@ -6598,13 +6598,13 @@ env_dup(VALUE obj)
  *
  *  === Creating a \Hash
  *
- *  Here are three ways to create a \Hash:
+ *  You can create a \Hash object explicitly with:
  *
- *  - \Method <tt>Hash.new</tt>
+ *  - A {hash literal}[doc/syntax/literals_rdoc.html#label-Hash+Literals].
- *  - \Method <tt>Hash[]</tt>
- *  - Literal form: <tt>{}</tt>.
  *
- *  ---
+ *  You can convert certain objects to Hashes with:
+ *
+ *  - \Method {Hash}[Kernel.html#method-i-Hash].
  *
  *  You can create a \Hash by calling method Hash.new.
  *
@@ -6614,8 +6614,6 @@ env_dup(VALUE obj)
  *    h # => {}
  *    h.class # => Hash
  *
- *  ---
- *
  *  You can create a \Hash by calling method Hash.[].
  *
  *  Create an empty Hash:
@@ -6628,8 +6626,6 @@ env_dup(VALUE obj)
  *    h = Hash[foo: 0, bar: 1, baz: 2]
  *    h # => {:foo=>0, :bar=>1, :baz=>2}
  *
- *  ---
- *
  *  You can create a \Hash by using its literal form (curly braces).
  *
  *  Create an empty \Hash:

numeric.c

@@ -948,8 +948,11 @@ num_negative_p(VALUE num)
  *
  *  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-Float+Literals].
- *  - A {floating-point literal}[doc/syntax/literals_rdoc.html#label-Floating-Point+Literals].
+ *
+ *  You can convert certain objects to Floats with:
+ *
+ *  - \Method {Float}[Kernel.html#method-i-Float].
  *
  *  == What's Here
  *
@@ -3479,9 +3482,12 @@ rb_num2ull(VALUE val)
  *
  * 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].
  *
+ * You can convert certain objects to Integers with:
+ *
+ * - \Method {Integer}[Kernel.html#method-i-Integer].
+ *
  * An attempt to add a singleton method to an instance of this class
  * causes an exception to be raised.
  *

proc.c

@@ -3845,7 +3845,8 @@ proc_ruby2_keywords(VALUE procval)
  *
  *      lambda1 = lambda {|x| x**2 }
  *
- * * Use the Lambda literal syntax (also constructs a proc with lambda semantics):
+ * * Use the {Lambda proc literal}[doc/syntax/literals_rdoc.html#label-Lambda+Proc+Literals] syntax
+ *   (also constructs a proc with lambda semantics):
  *
  *      lambda2 = ->(x) { x**2 }
  *

range.c

@@ -2050,14 +2050,16 @@ range_count(int argc, VALUE *argv, VALUE range)
 /* A \Range object represents a collection of values
  * that are between given begin and end values.
  *
- * A range may be created using a literal:
+ * You can create an \Range object explicitly with:
  *
- *   # Ranges that use '..' to include the given end value.
+ * - A {range literal}[doc/syntax/literals_rdoc.html#label-Range+Literals]:
- *   (1..4).to_a      # => [1, 2, 3, 4]
+ *
- *   ('a'..'d').to_a  # => ["a", "b", "c", "d"]
+ *     # Ranges that use '..' to include the given end value.
- *   # Ranges that use '...' to exclude the given end value.
+ *     (1..4).to_a      # => [1, 2, 3, 4]
- *   (1...4).to_a     # => [1, 2, 3]
+ *     ('a'..'d').to_a  # => ["a", "b", "c", "d"]
- *   ('a'...'d').to_a # => ["a", "b", "c"]
+ *     # Ranges that use '...' to exclude the given end value.
+ *     (1...4).to_a     # => [1, 2, 3]
+ *     ('a'...'d').to_a # => ["a", "b", "c"]
  *
  * A range may be created using method Range.new:
  *

rational.c

@@ -2715,13 +2715,19 @@ nurat_s_convert(int argc, VALUE *argv, VALUE klass)
  * a/b (b>0), where a is the numerator and b is the denominator.
  * Integer a equals rational a/1 mathematically.
  *
- * In Ruby, you can create rational objects with the Kernel#Rational,
+ * You can create a \Rational object explicitly with:
- * to_r, or rationalize methods or by suffixing +r+ to a literal.
+ *
- * The return values will be irreducible fractions.
+ * - A {rational literal}[doc/syntax/literals_rdoc.html#label-Rational+Literals].
+ *
+ * You can convert certain objects to Rationals with:
+ *
+ * - \Method {Rational}[Kernel.html#method-i-Rational].
+ *
+ * Examples
  *
  *    Rational(1)      #=> (1/1)
  *    Rational(2, 3)   #=> (2/3)
- *    Rational(4, -6)  #=> (-2/3)
+ *    Rational(4, -6)  #=> (-2/3) # Reduced.
  *    3.to_r           #=> (3/1)
  *    2/3r             #=> (2/3)
  *

re.c

@@ -4082,6 +4082,10 @@ re_warn(const char *s)
  *  and <code>%r{...}</code> literals, and by the Regexp::new
  *  constructor.
  *
+ *  You can create a \Regexp object explicitly with:
+ *
+ *  - A {regexp literal}[doc/syntax/literals_rdoc.html#label-Regexp+Literals].
+ *
  *  :include: doc/regexp.rdoc
  */
 

string.c

@@ -11152,15 +11152,18 @@ rb_str_unicode_normalized_p(int argc, VALUE *argv, VALUE str)
 /**********************************************************************
  * Document-class: Symbol
  *
- *  Symbol objects represent named identifiers inside the Ruby interpreter. They
+ * Symbol objects represent named identifiers inside the Ruby interpreter.
- *  are generated using the <code>:name</code> and
+ *
- *  <code>:"string"</code> literals syntax, and by the various
+ * You can create a \Symbol object explicitly with:
- *  <code>to_sym</code> methods. The same Symbol object will be
+ *
- *  created for a given name or string for the duration of a program's
+ * - A {symbol literal}[doc/syntax/literals_rdoc.html#label-Symbol+Literals].
- *  execution, regardless of the context or meaning of that name. Thus
+ *
- *  if <code>Fred</code> is a constant in one context, a method in
+ * The same Symbol object will be
- *  another, and a class in a third, the Symbol <code>:Fred</code>
+ * created for a given name or string for the duration of a program's
- *  will be the same object in all three contexts.
+ * execution, regardless of the context or meaning of that name. Thus
+ * if <code>Fred</code> is a constant in one context, a method in
+ * another, and a class in a third, the Symbol <code>:Fred</code>
+ * will be the same object in all three contexts.
  *
  *     module One
  *       class Fred
@@ -11795,6 +11798,15 @@ rb_enc_interned_str_cstr(const char *ptr, rb_encoding *enc)
  *  String objects differ from Symbol objects in that Symbol objects are
  *  designed to be used as identifiers, instead of text or data.
  *
+ *  You can create a \String object explicitly with:
+ *
+ *  - A {string literal}[doc/syntax/literals_rdoc.html#label-String+Literals].
+ *  - A {heredoc literal}[doc/syntax/literals_rdoc.html#label-Here+Document+Literals].
+ *
+ *  You can convert certain objects to Strings with:
+ *
+ *  - \Method {String}[Kernel.html#method-i-String].
+ *
  *  Some \String methods modify +self+.
  *  Typically, a method whose name ends with <tt>!</tt> modifies +self+
  *  and returns +self+;