improve docs for Pry::Method

lib/pry/method.rb

@@ -3,6 +3,10 @@ class Pry
     include RbxMethod if defined?(RUBY_ENGINE) && RUBY_ENGINE =~ /rbx/
 
     class << self
+      # Given a string representing a method name and optionally a binding to
+      # search in, find and return the requested method wrapped in a `Pry::Method`
+      # instance.
+      #
       # @param [String, nil] name The name of the method to retrieve, or `nil` to
       #   delegate to `from_binding` instead.
       # @param [Binding] target The context in which to search for the method.
@@ -11,7 +15,8 @@ class Pry
       #   contain any context.
       # @option options [Boolean] :methods Look for a bound/singleton method if `name` doesn't
       #   contain any context.
-      # @return [Pry::Method, nil]
+      # @return [Pry::Method, nil] A `Pry::Method` instance containing the requested
+      #   method, or `nil` if no method could be located matching the parameters.
       def from_str(name, target=TOPLEVEL_BINDING, options={})
         if name.nil?
           from_binding(target)
@@ -34,8 +39,10 @@ class Pry
       # Given a `Binding`, try to extract the `::Method` it originated from and
       # use it to instantiate a `Pry::Method`. Return `nil` if this isn't
       # possible.
+      #
       # @param [Binding] b
       # @return [Pry::Method, nil]
+      #
       def from_binding(b)
         meth_name = b.eval('__method__')
         if [:__script__, nil, :__binding__, :__binding_impl__].include?(meth_name)
@@ -48,6 +55,7 @@ class Pry
       # Given a `Class` or `Module` and the name of a method, try to
       # instantiate a `Pry::Method` containing the instance method of
       # that name. Return `nil` if no such method exists.
+      #
       # @param [Class, Module] klass
       # @param [String] name
       # @return [Pry::Method, nil]
@@ -59,6 +67,7 @@ class Pry
       # Given an object and the name of a method, try to instantiate
       # a `Pry::Method` containing the method of that name bound to
       # that object. Return `nil` if no such method exists.
+      #
       # @param [Object] obj
       # @param [String] name
       # @return [Pry::Method, nil]
@@ -67,13 +76,15 @@ class Pry
       end
     end
 
-    # @param [Method, UnboundMethod, Proc] method
+    # A new instance of `Pry::Method` wrapping the given `::Method`, `UnboundMethod`, or `Proc`.
+    #
+    # @param [::Method, UnboundMethod, Proc] method
+    # @return [Pry::Method]
     def initialize(method)
       @method = method
     end
 
-    # Return the source code of the method, or `nil` if it's unavailable.
+    # @return [String, nil] The source code of the method, or `nil` if it's unavailable.
-    # @return [String, nil]
     def source
       @source ||= case source_type
         when :c
@@ -93,8 +104,8 @@ class Pry
         end
     end
 
-    # Return the documentation for the method, of `nil` if it's unavailable.
+    # @return [String, nil] The documentation for the method, or `nil` if it's
-    # @return [String, nil]
+    #   unavailable.
     # @raise [CommandError] Raises when the method was defined in the REPL.
     def doc
       @doc ||= case source_type
@@ -112,10 +123,9 @@ class Pry
         end
     end
 
-    # Return a `Symbol` representing the "source type" of this method. The
+    # @return [Symbol] The source type of the method. The options are
-    # options are `:ruby` for ordinary Ruby methods, `:c` for methods
+    #   `:ruby` for ordinary Ruby methods, `:c` for methods written in
-    # written in C, or `:rbx` for Rubinius core methods written in Ruby.
+    #   C, or `:rbx` for Rubinius core methods written in Ruby.
-    # @return [Symbol]
     def source_type
       if defined?(RUBY_ENGINE) && RUBY_ENGINE =~ /rbx/
         if core? then :rbx else :ruby end
@@ -124,22 +134,20 @@ class Pry
       end
     end
 
-    # Return the name of the file the method is defined in, or `nil` if
+    # @return [String, nil] The name of the file the method is defined in, or
-    # the filename is unavailable.
+    #   `nil` if the filename is unavailable.
-    # @return [String, nil]
     def source_file
       source_location.nil? ? nil : source_location.first
     end
 
-    # Return the line of code in `source_file` which begins the definition
+    # @return [Fixnum, nil] The line of code in `source_file` which begins
-    # of the method, or `nil` if that information is unavailable.
+    #   the method's definition, or `nil` if that information is unavailable.
-    # @return [Fixnum, nil]
     def source_line
       source_location.nil? ? nil : source_location.last
     end
 
-    # Return a `Symbol` representing the visibility of the method. The
+    # @return [Symbol] The visibility of the method. May be `:public`,
-    # options are `:public`, `:protected`, or `:private`.
+    #   `:protected`, or `:private`.
     def visibility
       if owner.public_instance_methods.include?(name)
         :public
@@ -152,12 +160,11 @@ class Pry
       end
     end
 
-    # Return a representation of the method's signature, including its
+    # @return [String] A representation of the method's signature, including its
-    # name and parameters. Optional and "rest" parameters are marked with `*`
+    #   name and parameters. Optional and "rest" parameters are marked with `*`
-    # and block parameters with `&`. If the parameter names are unavailable,
+    #   and block parameters with `&`. If the parameter names are unavailable,
-    # they're given numbered names instead.
+    #   they're given numbered names instead.
-    # Paraphrased from `awesome_print` gem.
+    #   Paraphrased from `awesome_print` gem.
-    # @return [String]
     def signature
       if respond_to?(:parameters)
         args = parameters.inject([]) do |arr, (type, name)|
@@ -177,12 +184,12 @@ class Pry
       "#{name}(#{args.join(', ')})"
     end
 
-    # @return [Boolean]
+    # @return [Boolean] Was the method defined outside a source file?
     def dynamically_defined?
-      source_file ? !!(source_file =~ /(\(.*\))|<.*>/) : nil
+      !!(source_file and source_file =~ /(\(.*\))|<.*>/)
     end
 
-    # @return [Boolean]
+    # @return [Boolean] Was the method defined within the Pry REPL?
     def pry_method?
       source_file == Pry.eval_path
     end
@@ -209,6 +216,7 @@ class Pry
       super or @method.respond_to?(method_name)
     end
 
+    # Delegate any unknown calls to the wrapped method.
     def method_missing(method_name, *args, &block)
       @method.send(method_name, *args, &block)
     end