1 files changed, 113 insertions, 13 deletions
diff --git a/doc/syntax/methods.rdoc b/doc/syntax/methods.rdoc
index 8183d48612..b3233e647a 100644
--- a/doc/syntax/methods.rdoc
+++ b/doc/syntax/methods.rdoc
@@ -9,11 +9,64 @@ definition:
 
 A method definition consists of the +def+ keyword, a method name, the body of
 the method, then the +end+ keyword.  When called the method will execute the
-body of the method.  This method returns <tt>2</tt>.
+body of the method.  This method returns +2+.
 
-A method may be defined on another object.  You may define a "class
-method" (a method that is called on the class, not an instance of the class)
-like this:
+== Return values
+
+By default, a method returns the last expression that was evaluated in the body
+of the method.  In the example above, the last (and only) expression evaluated
+was the simple sum <code>1 + 1</code>.  The +return+ keyword can be used to
+make it explicit that a method returns a value.
+
+  def one_plus_one
+    return 1 + 1
+  end
+
+It can also be used to make a method return before the last expression is
+evaluated.
+
+  def two_plus_two
+    return 2 + 2
+    1 + 1  # this expression is never evaluated
+  end
+
+== Scope
+
+The standard syntax to define a method:
+
+  def my_method
+    # ...
+  end
+
+add the method to a class.  You can define an instance method on a specific
+class with the +class+ keyword:
+
+  class C
+    def my_method
+      # ...
+    end
+  end
+
+In many languages, the +class+ keyword lets the compiler know that you're
+creating a class.  This is true in Ruby, too, the first time you use the
+_class_ keyword: when it sees that you're _opening_ a class for
+the first time, it creates it.  When you open a class that already exists, Ruby
+enables to you _extend_ it with new methods.  You can even extend core
+classes:
+
+  class String
+    def hello
+      "Hello, world!"
+    end
+  end
+
+  "".hello # returns "Hello, world!"
+
+However, This is somewhat risky due to namespace pollution so this ability is
+best used sparingly.
+
+A method may be defined on another object.  You may define a "class method" (a
+method that is defined on the class, not an instance of the class) like this:
 
   class C
     def self.my_method
@@ -21,16 +74,63 @@ like this:
     end
   end
 
-You may also define methods this way on any object:
+or a more concrete example:
 
-  string = "my string"
-  def string.my_method
-    # ...
+  class String
+    def self.hello
+      "Hello, world!"
+    end
   end
 
-This is called a "singleton method".  +my_method+ will only exist on this
-string instance.  Other strings will not have +my_method+.  You may also
-override existing methods on just one object this way.
+  String.hello # returns "Hello, world!"
+
+However, this is simply a special case of a greater syntactical power in Ruby,
+the ability to add methods to any object.  Classes are objects, so adding
+class methods is simply adding methods to the Class object.
+
+The syntax for adding a method to an object is as follows:
+
+  greeting = "Hello"
+
+  def greeting.broaden
+    self + ", world!"
+  end
+
+  greeting.broaden # returns "Hello, world!"
+
+_self_ is a keyword referring to the current object under consideration
+by the compiler, which might make the use of +self+ in defining a class
+method above a little clearer.  Indeed, the example of adding a +hello+
+method to the class +String+ can be rewritten thus:
+
+  def String.hello
+    "Hello, world!"
+  end
+
+A method defined like this is called a "singleton method".  +broaden+ will only
+exist on the string instance +greeting+.  Other strings will not have +broaden+.
+
+== Overriding
+
+When Ruby encounters the +def+ keyword, it doesn't consider it an error if the
+method already exists: it simply redefines it.  This is called
+_overriding_.  Rather like extending core classes, this is a potentially
+dangerous ability, and should be used sparingly because it can cause unexpected
+results.  For example, consider this irb session:
+
+  >> "43".to_i
+  => 43
+  >> class String
+  >>   def to_i
+  >>     42
+  >>   end
+  >> end
+  => nil
+  >> "43".to_i
+  => 42
+
+This will effectively sabotage any code which makes use of the method
+<code>String#to_i</code> to parse numbers from strings.
 
 == Arguments
 
@@ -42,8 +142,8 @@ A method may accept arguments.  The argument list follows the method name:
 
 When called, the user of the +add_one+ method must provide an argument.  The
 argument is a local variable in the method body.  The method will then add one
-to this argument and return the value.  If given <tt>1</tt> this method will
-return <tt>2</tt>.
+to this argument and return the value.  If given +1+ this method will
+return +2+.
 
 The parentheses around the arguments are optional: