[DOC] Doc enhancements for ERB

lib/erb.rb

@@ -777,12 +777,7 @@ class ERB
   # :call-seq:
   #   self.version -> string
   #
-  # Returns the string revision for \ERB:
-  #
-  # ```
-  # ERB.version # => "4.0.4"
-  # ```
-  #
+  # Returns the string \ERB version.
   def self.version
     VERSION
   end
@@ -815,7 +810,9 @@ def self.version
   # **Keyword Argument `eoutvar`**
   #
   # The string value of keyword argument `eoutvar` specifies the name of the variable
-  # that method #result uses to construct its result string.
+  # that method #result uses to construct its result string;
+  # see #src.
+  #
   # This is useful when you need to run multiple \ERB templates through the same binding
   # and/or when you want to control where output ends up.
   #
@@ -868,25 +865,82 @@ def initialize(str, safe_level=NOT_GIVEN, legacy_trim_mode=NOT_GIVEN, legacy_eou
     @lineno = 0
     @_init = self.class.singleton_class
   end
+
+  # :markup: markdown
+  #
+  # Placeholder constant; used as default value for certain method arguments.
   NOT_GIVEN = defined?(Ractor) ? Ractor.make_shareable(Object.new) : Object.new
   private_constant :NOT_GIVEN
 
-  ##
-  # Creates a new compiler for ERB.  See ERB::Compiler.new for details
+  # :markup: markdown
+  #
+  # :call-seq:
+  #   make_compiler -> erb_compiler
+  #
+  # Returns a new ERB::Compiler with the given `trim_mode`;
+  # for `trim_mode` values, see ERB.new:
+  #
+  # ```
+  # ERB.new('').make_compiler(nil)
+  # # => #<ERB::Compiler:0x000001cff9467678 @insert_cmd="print", @percent=false, @post_cmd=[], @pre_cmd=[], @put_cmd="print", @trim_mode=nil>
+  # ```
+  #
 
   def make_compiler(trim_mode)
     ERB::Compiler.new(trim_mode)
   end
 
-  # The Ruby code generated by ERB
+  # :markup: markdown
+  #
+  # Returns a string containing the Ruby code that, when executed, generates the result;
+  # the code is executed by method #result,
+  # and by its wrapper methods #result_with_hash and #run:
+  #
+  # ```
+  # s = 'The time is <%= Time.now %>.'
+  # template = ERB.new(s)
+  # template.src
+  # # => "#coding:UTF-8\n_erbout = +''; _erbout.<< \"The time is \".freeze; _erbout.<<(( Time.now ).to_s); _erbout.<< \".\".freeze; _erbout"
+  # template.result
+  # # => "The time is 2025-09-18 15:58:08 -0500."
+  # ```
+  #
+  # In a more readable format:
+  #
+  # ```
+  #   # puts template.src.split('; ')
+  #   # #coding:UTF-8
+  #   # _erbout = +''
+  #   # _erbout.<< "The time is ".freeze
+  #   # _erbout.<<(( Time.now ).to_s)
+  #   # _erbout.<< ".".freeze
+  #   # _erbout
+  # ```
+  #
+  # Variable `_erbout` is used to store the intermediate results in the code;
+  # the name `_erbout` is the default in ERB.new,
+  # and can be changed via keyword argument `eoutvar`:
+  #
+  # ```
+  # template = ERB.new(s, eoutvar: '_foo')
+  # puts template.src.split('; ')
+  # #coding:UTF-8
+  # _foo = +''
+  # _foo.<< "The time is ".freeze
+  # _foo.<<(( Time.now ).to_s)
+  # _foo.<< ".".freeze
+  # _foo
+  # ```
+  #
   attr_reader :src
 
   # :markup: markdown
   #
   # Returns the encoding of `self`;
-  # see [encoding][encoding].
+  # see [Encodings][encodings]:
+  #
+  # [encodings]: rdoc-ref:ERB@Encodings
   #
-  # [encoding]: https://docs.ruby-lang.org/en/master/Encoding.html
   attr_reader :encoding
 
   # :markup: markdown
@@ -920,10 +974,35 @@ def location=((filename, lineno))
     @lineno = lineno if lineno
   end
 
+  # :markup: markdown
   #
-  # Can be used to set _eoutvar_ as described in ERB::new.  It's probably
-  # easier to just use the constructor though, since calling this method
-  # requires the setup of an ERB _compiler_ object.
+  # :call-seq:
+  #   set_eoutvar(compiler, eoutvar = '_erbout') -> [eoutvar]
+  #
+  # Sets the `eoutvar` value in the ERB::Compiler object `compiler`;
+  # returns a 1-element array containing the value of `eoutvar`:
+  #
+  # ```
+  # template = ERB.new('')
+  # compiler = template.make_compiler(nil)
+  # pp compiler
+  # #<ERB::Compiler:0x000001cff8a9aa00
+  #  @insert_cmd="print",
+  #  @percent=false,
+  #  @post_cmd=[],
+  #  @pre_cmd=[],
+  #  @put_cmd="print",
+  #  @trim_mode=nil>
+  # template.set_eoutvar(compiler, '_foo') # => ["_foo"]
+  # pp compiler
+  # #<ERB::Compiler:0x000001cff8a9aa00
+  #  @insert_cmd="_foo.<<",
+  #  @percent=false,
+  #  @post_cmd=["_foo"],
+  #  @pre_cmd=["_foo = +''"],
+  #  @put_cmd="_foo.<<",
+  #  @trim_mode=nil>
+  # ```
   #
   def set_eoutvar(compiler, eoutvar = '_erbout')
     compiler.put_cmd = "#{eoutvar}.<<"

lib/erb/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 class ERB
-  # The version string
+  # The string \ERB version.
   VERSION = '5.0.2'
 end