[DOC] Tweaks for module Base64

Author: BurdetteLamar

lib/base64.rb

@@ -2,7 +2,7 @@
 #
 # \Module \Base64 provides methods for:
 #
-# - Encoding a binary string (containing non-ASCII characters)
+# - \Encoding a binary string (containing non-ASCII characters)
 #   as a string of printable ASCII characters.
 # - Decoding such an encoded string.
 #
@@ -27,7 +27,7 @@
 #
 #   require 'base64'
 #
-# == Encoding Character Sets
+# == \Encoding Character Sets
 #
 # A \Base64-encoded string consists only of characters from a 64-character set:
 #
@@ -140,7 +140,7 @@
 #   Base64.strict_decode64("MDEyMzQ1Njc=")  # => "01234567"
 #   Base64.strict_decode64("MDEyMzQ1Njc==") # Raises ArgumentError
 #
-# \Method Base64.urlsafe_decode64 allows padding in +str+,
+# \Method Base64.urlsafe_decode64 allows padding in the encoded string,
 # which if present, must be correct:
 # see {Padding}[Base64.html#module-Base64-label-Padding], above:
 #
@@ -187,7 +187,10 @@ module Base64
 
   module_function
 
-  # Returns a string containing the RFC-2045-compliant \Base64-encoding of +bin+.
+  # :call-seq:
+  #   Base64.encode64(string) -> encoded_string
+  #
+  # Returns a string containing the RFC-2045-compliant \Base64-encoding of +string+.
   #
   # Per RFC 2045, the returned string may contain the URL-unsafe characters
   # <tt>+</tt> or <tt>/</tt>;
@@ -220,19 +223,22 @@ def encode64(bin)
     [bin].pack("m")
   end
 
+  # :call-seq:
+  #   Base64.decode(encoded_string) -> decoded_string
+  #
   # Returns a string containing the decoding of an RFC-2045-compliant
-  # \Base64-encoded string +str+:
+  # \Base64-encoded string +encoded_string+:
   #
   #   s = "VGhpcyBpcyBsaW5lIDEKVGhpcyBpcyBsaW5lIDIK\n"
   #   Base64.decode64(s) # => "This is line 1\nThis is line 2\n"
   #
-  # Non-\Base64 characters in +str+ are ignored;
+  # Non-\Base64 characters in +encoded_string+ are ignored;
   # see {Encoding Character Set}[Base64.html#module-Base64-label-Encoding+Character+Sets] above:
   # these include newline characters and characters <tt>-</tt> and <tt>/</tt>:
   #
   #   Base64.decode64("\x00\n-_") # => ""
   #
-  # Padding in +str+ (even if incorrect) is ignored:
+  # Padding in +encoded_string+ (even if incorrect) is ignored:
   #
   #   Base64.decode64("MDEyMzQ1Njc")   # => "01234567"
   #   Base64.decode64("MDEyMzQ1Njc=")  # => "01234567"
@@ -242,7 +248,10 @@ def decode64(str)
     str.unpack1("m")
   end
 
-  # Returns a string containing the RFC-2045-compliant \Base64-encoding of +bin+.
+  # :call-seq:
+  #   Base64.strict_encode64(string) -> encoded_string
+  #
+  # Returns a string containing the RFC-2045-compliant \Base64-encoding of +string+.
   #
   # Per RFC 2045, the returned string may contain the URL-unsafe characters
   # <tt>+</tt> or <tt>/</tt>;
@@ -274,21 +283,24 @@ def strict_encode64(bin)
     [bin].pack("m0")
   end
 
+  # :call-seq:
+  #   Base64.strict_decode64(encoded_string) -> decoded_string
+  #
   # Returns a string containing the decoding of an RFC-2045-compliant
-  # \Base64-encoded string +str+:
+  # \Base64-encoded string +encoded_string+:
   #
   #   s = "VGhpcyBpcyBsaW5lIDEKVGhpcyBpcyBsaW5lIDIK"
   #   Base64.strict_decode64(s) # => "This is line 1\nThis is line 2\n"
   #
-  # Non-\Base64 characters in +str+ not allowed;
+  # Non-\Base64 characters in +encoded_string+ are not allowed;
   # see {Encoding Character Set}[Base64.html#module-Base64-label-Encoding+Character+Sets] above:
   # these include newline characters and characters <tt>-</tt> and <tt>/</tt>:
   #
   #   Base64.strict_decode64("\n") # Raises ArgumentError
   #   Base64.strict_decode64('-')  # Raises ArgumentError
   #   Base64.strict_decode64('_')  # Raises ArgumentError
   #
-  # Padding in +str+, if present, must be correct:
+  # Padding in +encoded_string+, if present, must be correct:
   #
   #   Base64.strict_decode64("MDEyMzQ1Njc")   # Raises ArgumentError
   #   Base64.strict_decode64("MDEyMzQ1Njc=")  # => "01234567"
@@ -298,7 +310,10 @@ def strict_decode64(str)
     str.unpack1("m0")
   end
 
-  # Returns the RFC-4648-compliant \Base64-encoding of +bin+.
+  # :call-seq:
+  #   Base64.urlsafe_encode64(string) -> encoded_string
+  #
+  # Returns the RFC-4648-compliant \Base64-encoding of +string+.
   #
   # Per RFC 4648, the returned string will not contain the URL-unsafe characters
   # <tt>+</tt> or <tt>/</tt>,
@@ -332,16 +347,19 @@ def urlsafe_encode64(bin, padding: true)
     str
   end
 
-  # Returns the decoding of an RFC-4648-compliant \Base64-encoded string +str+:
+  # :call-seq:
+  #   Base64.urlsafe_decode64(encoded_string) -> decoded_string
+  #
+  # Returns the decoding of an RFC-4648-compliant \Base64-encoded string +encoded_string+:
   #
-  # +str+ may not contain non-Base64 characters;
+  # +encoded_string+ may not contain non-Base64 characters;
   # see {Encoding Character Set}[Base64.html#module-Base64-label-Encoding+Character+Sets] above:
   #
   #   Base64.urlsafe_decode64('+')  # Raises ArgumentError.
   #   Base64.urlsafe_decode64('/')  # Raises ArgumentError.
   #   Base64.urlsafe_decode64("\n") # Raises ArgumentError.
   #
-  # Padding in +str+, if present, must be correct:
+  # Padding in +encoded_string+, if present, must be correct:
   # see {Padding}[Base64.html#module-Base64-label-Padding], above:
   #
   #   Base64.urlsafe_decode64("MDEyMzQ1Njc") # => "01234567"