Enhanced RDoc for Symbol (#5795)

Treats:

    #==
    #inspect
    #name
    #to_s
    #to_sym
    #to_proc
    #succ
    #<=>
    #casecmp
    #casecmp?
    #=~
    #match
    #match?

2 files changed, 53 insertions, 0 deletions

diff --git a/doc/symbol/casecmp.rdoc b/doc/symbol/casecmp.rdoc
new file mode 100644
index 0000000000..9c286070b7
--- /dev/null
+++ b/doc/symbol/casecmp.rdoc
@@ -0,0 +1,27 @@
+Like Symbol#<=>, but case-insensitive;
+equivalent to <tt>self.to_s.casecmp(object.to_s)</tt>:
+
+  lower = :abc
+  upper = :ABC
+  upper.casecmp(lower) # => 0
+  lower.casecmp(lower) # => 0
+  lower.casecmp(upper) # => 0
+
+Returns nil if +self+ and +object+ have incompatible encodings,
+or if +object+ is not a symbol:
+
+  sym = 'äöü'.encode("ISO-8859-1").to_sym
+  other_sym = 'ÄÖÜ'
+  sym.casecmp(other_sym) # => nil
+  :foo.casecmp(2)        # => nil
+
+Unlike Symbol#casecmp?,
+case-insensitivity does not work for characters outside of 'A'..'Z' and 'a'..'z':
+
+  lower = :äöü
+  upper = :ÄÖÜ
+  upper.casecmp(lower) # => -1
+  lower.casecmp(lower) # => 0
+  lower.casecmp(upper) # => 1
+
+Related: Symbol#casecmp?, String#casecmp.
diff --git a/doc/symbol/casecmp_p.rdoc b/doc/symbol/casecmp_p.rdoc
new file mode 100644
index 0000000000..7102b54289
--- /dev/null
+++ b/doc/symbol/casecmp_p.rdoc
@@ -0,0 +1,26 @@
+Returns +true+ if +self+ and +object+ are equal after Unicode case folding,
+otherwise +false+:
+
+  lower = :abc
+  upper = :ABC
+  upper.casecmp?(lower) # => true
+  lower.casecmp?(lower) # => true
+  lower.casecmp?(upper) # => true
+
+Returns nil if +self+ and +object+ have incompatible encodings,
+or if +object+ is not a symbol:
+
+  sym = 'äöü'.encode("ISO-8859-1").to_sym
+  other_sym = 'ÄÖÜ'
+  sym.casecmp?(other_sym) # => nil
+  :foo.casecmp?(2)        # => nil
+
+Unlike Symbol#casecmp, works for characters outside of 'A'..'Z' and 'a'..'z':
+
+  lower = :äöü
+  upper = :ÄÖÜ
+  upper.casecmp?(lower) # => true
+  lower.casecmp?(lower) # => true
+  lower.casecmp?(upper) # => true
+
+Related: Symbol#casecmp, String#casecmp?.