Erb doc

lib/erb.rb

@@ -511,24 +511,32 @@
 #
 # ## Encodings
 #
-# In general, an \ERB result string (or Ruby code generated by \ERB)
-# has the same encoding as the string originally passed to ERB.new;
-# see [Encoding][encoding].
+# An \ERB template has an [encoding][encoding],
+# which is by default the encoding of the source string;
+# the result string will also have that encoding.
 #
-# You can specify the output encoding by adding a [magic comment][magic comments]
+# ```
+# s = <<EOT
+# <%# Comment. %>
+# EOT
+# template = ERB.new(s)
+# s.encoding               # => #<Encoding:UTF-8>
+# template.encoding        # => #<Encoding:UTF-8>
+# template.result.encoding # => #<Encoding:UTF-8>
+# ```
+#
+# You can specify a different encoding by adding a [magic comment][magic comments]
 # at the top of the given string:
 #
 # ```
-# s = <<EOF
+# s = <<EOT
 # <%#-*- coding: Big5 -*-%>
-#
-# Some text.
-# EOF
-# # => "<%#-*- coding: Big5 -*-%>\n\nSome text.\n"
-# s.encoding
-# # => #<Encoding:UTF-8>
-# ERB.new(s).result.encoding
-# # => #<Encoding:Big5>
+# <%# Comment. %>
+# EOT
+# template = ERB.new(s)
+# s.encoding               # => #<Encoding:UTF-8>
+# template.encoding        # => #<Encoding:Big5>
+# template.result.encoding # => #<Encoding:Big5>
 # ```
 #
 # ## Plain Text Example
@@ -830,7 +838,12 @@ def make_compiler(trim_mode)
   # The Ruby code generated by ERB
   attr_reader :src
 
-  # The encoding to eval
+  # :markup: markdown
+  #
+  # Returns the encoding of `self`;
+  # see [encoding][encoding].
+  #
+  # [encoding]: https://docs.ruby-lang.org/en/master/Encoding.html
   attr_reader :encoding
 
   # The optional _filename_ argument passed to Kernel#eval when the ERB code
@@ -873,7 +886,13 @@ def set_eoutvar(compiler, eoutvar = '_erbout')
     compiler.post_cmd = [eoutvar]
   end
 
-  # Generate results and print them. (see ERB#result)
+  # :markup: markdown
+  #
+  # :call-seq:
+  #   run(binding = new_toplevel) -> nil
+  #
+  # Like #result, but prints the result string (instead of returning it);
+  # returns `nil`.
   def run(b=new_toplevel)
     print self.result(b)
   end
@@ -923,10 +942,21 @@ def result_with_hash(hash)
     result(b)
   end
 
-  ##
-  # Returns a new binding each time *near* TOPLEVEL_BINDING for runs that do
-  # not specify a binding.
-
+  # :markup: markdown
+  #
+  # :call-seq:
+  #   new_toplevel(symbols) -> new_binding
+  #
+  # Returns a new binding based on `TOPLEVEL_BINDING`;
+  # used to create a default binding for a call to #result.
+  #
+  # See [Default Binding][default binding].
+  #
+  # Argument `symbols` is an array of symbols;
+  # each symbol `symbol` is used to define (unless already defined) a variable in the binding
+  # whose name is `symbol` and whose value is `nil`.
+  #
+  # [default binding]: rdoc-ref:ERB@Default+Binding
   def new_toplevel(vars = nil)
     b = TOPLEVEL_BINDING
     if vars