unicode_normalize.rb: improve docs

* lib/unicode_normalize.rb: [DOC] improve docs for
  String#{unicode_normalize,unicode_normalized?}: rdoc formatting,
  adopt style of other String methods (drop heading and "Examples").

git-svn-id: svn+ssh://ci.ruby-lang.org/ruby/trunk@58331 b2dd03c8-39d4-4d8f-98ff-823fe69b080e

lib/unicode_normalize.rb

@@ -7,24 +7,22 @@
 # additions to class String for Unicode normalization
 #++
 class String
-  # === Unicode Normalization
-  #
+
   # :call-seq:
   #    str.unicode_normalize(form=:nfc)
   #
-  # Returns a normalized form of +str+, using Unicode normalizations
-  # NFC, NFD, NFKC, or NFKD. The normalization form used is determined
-  # by +form+, which is any of the four values :nfc, :nfd, :nfkc, or :nfkd.
-  # The default is :nfc.
+  # Unicode Normalization---Returns a normalized form of +str+,
+  # using Unicode normalizations NFC, NFD, NFKC, or NFKD.
+  # The normalization form used is determined by +form+, which can
+  # be any of the four values +:nfc+, +:nfd+, +:nfkc+, or +:nfkd+.
+  # The default is +:nfc+.
   #
   # If the string is not in a Unicode Encoding, then an Exception is raised.
-  # In this context, 'Unicode Encoding' means any of  UTF-8, UTF-16BE/LE,
-  # and UTF-32BE/LE, as well as GB18030, UCS_2BE, and UCS_4BE. Anything
-  # else than UTF-8 is implemented by converting to UTF-8,
+  # In this context, 'Unicode Encoding' means any of UTF-8, UTF-16BE/LE,
+  # and UTF-32BE/LE, as well as GB18030, UCS_2BE, and UCS_4BE.
+  # Anything other than UTF-8 is implemented by converting to UTF-8,
   # which makes it slower than UTF-8.
   #
-  # _Examples_
-  #
   #   "a\u0300".unicode_normalize        #=> 'à' (same as "\u00E0")
   #   "a\u0300".unicode_normalize(:nfc)  #=> 'à' (same as "\u00E0")
   #   "\u00E0".unicode_normalize(:nfd)   #=> 'à' (same as "a\u0300")
@@ -57,14 +55,12 @@ class String
   #    str.unicode_normalized?(form=:nfc)
   #
   # Checks whether +str+ is in Unicode normalization form +form+,
-  # which is any of the four values :nfc, :nfd, :nfkc, or :nfkd.
-  # The default is :nfc.
+  # which can be any of the four values +:nfc+, +:nfd+, +:nfkc+, or +:nfkd+.
+  # The default is +:nfc+.
   #
   # If the string is not in a Unicode Encoding, then an Exception is raised.
   # For details, see String#unicode_normalize.
   #
-  # _Examples_
-  #
   #   "a\u0300".unicode_normalized?        #=> false
   #   "a\u0300".unicode_normalized?(:nfd)  #=> true
   #   "\u00E0".unicode_normalized?         #=> true