[DOC] Doc for #def_method and #def_module

Author: BurdetteLamar

lib/erb.rb

@@ -1095,30 +1095,56 @@ def new_toplevel(vars = nil)
   end
   private :new_toplevel
 
-  # Define _methodname_ as instance method of _mod_ from compiled Ruby source.
+  # :markup: markdown
+  #
+  # :call-seq:
+  #   def_method(module, method_signature, filename = '(ERB)') -> method_name
+  #
+  # Creates and returns a new instance method in the given module `module`;
+  # returns the method name as a symbol.
+  #
+  # The method is created from the given `method_signature`,
+  # which consists of the method name and its argument names (if any).
+  #
+  # The `filename` sets the value of #filename;
+  # see [Error Reporting][error reporting].
+  #
+  # [error reporting]: rdoc-ref:ERB@Error+Reporting
+  #
+  # ```
+  # s = '<%= arg1 %> <%= arg2 %>'
+  # template = ERB.new(s)
+  # MyModule = Module.new
+  # template.def_method(MyModule, 'render(arg1, arg2)') # => :render
+  # class MyClass; include MyModule; end
+  # MyClass.new.render('foo', 123)                      # => "foo 123"
+  # ```
   #
-  # example:
-  #   filename = 'example.rhtml'   # 'arg1' and 'arg2' are used in example.rhtml
-  #   erb = ERB.new(File.read(filename))
-  #   erb.def_method(MyClass, 'render(arg1, arg2)', filename)
-  #   print MyClass.new.render('foo', 123)
   def def_method(mod, methodname, fname='(ERB)')
     src = self.src.sub(/^(?!#|$)/) {"def #{methodname}\n"} << "\nend\n"
     mod.module_eval do
       eval(src, binding, fname, -1)
     end
   end
 
-  # Create unnamed module, define _methodname_ as instance method of it, and return it.
-  #
-  # example:
-  #   filename = 'example.rhtml'   # 'arg1' and 'arg2' are used in example.rhtml
-  #   erb = ERB.new(File.read(filename))
-  #   erb.filename = filename
-  #   MyModule = erb.def_module('render(arg1, arg2)')
-  #   class MyClass
-  #     include MyModule
-  #   end
+  # :markup: markdown
+  #
+  # :call-seq:
+  #    def_module(method_name = 'erb') -> new_module
+  #
+  # Returns a new nameless module that has instance method `method_name`.
+  #
+  # ```
+  # s = '<%= arg1 %> <%= arg2 %>'
+  # template = ERB.new(s)
+  # MyModule = template.def_module('render(arg1, arg2)')
+  # class MyClass
+  #   include MyModule
+  # end
+  # MyClass.new.render('foo', 123)
+  # # => "foo 123"
+  # ```
+  #
   def def_module(methodname='erb')
     mod = Module.new
     def_method(mod, methodname, @filename || '(ERB)')