version 0.2.0, support for method comments (and a few minor changes), thanks to Adam Sanderson

* Merged in Adam's changes
* Refactored source_helper to reflect comment_helper style
* Made some adjustments to Adam's code: removed buffer.strip, now doing an lstrip on each line before adding to buffer
* No longer including blank lines in comment buffer (blank lines ignored)
* Added large number of comment-related tests

5 files changed, 174 insertions, 36 deletions

diff --git a/README.markdown b/README.markdown
index 44382c2..820be23 100644
--- a/README.markdown
+++ b/README.markdown
@@ -11,17 +11,19 @@ in Ruby 1.9
 `method_source` is a utility to return a method's sourcecode as a
 Ruby string. Also returns `Proc` and `Lambda` sourcecode.
 
+Method comments can also be extracted using the `comment` method.
+
 It is written in pure Ruby (no C).
 
-`method_source` provides the `source` method to the `Method` and
+`method_source` provides the `source` and `comment` methods to the `Method` and
 `UnboundMethod` and `Proc` classes.
 
 * Install the [gem](https://rubygems.org/gems/method_source): `gem install method_source`
 * Read the [documentation](http://rdoc.info/github/banister/method_source/master/file/README.markdown)
 * See the [source code](http://github.com/banister/method_source)
 
-Example: methods
-----------------
+Example: display method source
+------------------------------
 
     Set.instance_method(:merge).source.display
     # =>
@@ -35,6 +37,14 @@ Example: methods
       self
     end
 
+Example: display method comments
+--------------------------------
+
+    Set.instance_method(:merge).comment.display
+    # =>
+    # Merges the elements of the given enumerable object to the set and
+    # returns self.=> nil
+
 Limitations:
 ------------
 
@@ -49,3 +59,8 @@ Possible Applications:
   for extra fun.
 
 
+Special Thanks
+--------------
+
+[Adam Sanderson](https://github.com/adamsanderson) for `comment` functionality.
+
diff --git a/lib/method_source.rb b/lib/method_source.rb
index 57397c7..ecb546e 100644
--- a/lib/method_source.rb
+++ b/lib/method_source.rb
@@ -20,9 +20,8 @@ module MethodSource
     !!Ripper::SexpBuilder.new(code).parse
   end
 
-  # Helper method responsible for opening source file and advancing to
-  # the correct linenumber. Defined here to avoid polluting `Method`
-  # class.
+  # Helper method responsible for extracting method body.
+  # Defined here to avoid polluting `Method` class.
   # @param [Array] source_location The array returned by Method#source_location
   # @return [File] The opened source file
   def self.source_helper(source_location)
@@ -31,7 +30,44 @@ module MethodSource
     file_name, line = source_location
     file = File.open(file_name)
     (line - 1).times { file.readline }
-    file
+
+    code = ""
+    loop do
+      val = file.readline
+      code << val
+      
+      return code if MethodSource.valid_expression?(code)
+    end
+    
+  ensure
+    file.close if file
+  end
+  
+  # Helper method responsible for opening source file and buffering up
+  # the comments for a specified method. Defined here to avoid polluting 
+  # `Method` class.
+  # @param [Array] source_location The array returned by Method#source_location
+  # @return [String] The comments up to the point of the method.
+  def self.comment_helper(source_location)
+    return nil if !source_location.is_a?(Array)
+    
+    file_name, line = source_location
+    file = File.open(file_name)
+    buffer = ""
+    (line - 1).times do
+      line = file.readline
+      # Add any line that is a valid ruby comment, 
+      # but clear as soon as we hit a non comment line.
+      if (line =~ /^\s*#/) || (line =~ /^\s*$/)
+        buffer << line.lstrip
+      else
+        buffer.clear
+      end
+    end
+    
+    buffer
+  ensure
+    file.close if file
   end
   
   # This module is to be included by `Method` and `UnboundMethod` and
@@ -49,26 +85,34 @@ module MethodSource
     #       self
     #     end
     def source
-      file = nil
-      
       if respond_to?(:source_location)
-        file = MethodSource.source_helper(source_location)
+        source = MethodSource.source_helper(source_location)
         
-        raise "Cannot locate source for this method: #{name}" if !file
+        raise "Cannot locate source for this method: #{name}" if !source
       else
         raise "Method#source not supported by this Ruby version (#{RUBY_VERSION})"
       end
-
-      code = ""
-      loop do
-        val = file.readline
-        code += val
+      
+      source
+    end
+    
+    # Return the comments associated with the method as a string.
+    # (This functionality is only supported in Ruby 1.9 and above)
+    # @return [String] The method's comments as a string
+    # @example
+    #  Set.instance_method(:clear).comment.display
+    #  =>
+    #     # Removes all elements and returns self.
+    def comment
+      if respond_to?(:source_location)
+        comment = MethodSource.comment_helper(source_location)
         
-        return code if MethodSource.valid_expression?(code)
+        raise "Cannot locate source for this method: #{name}" if !comment
+      else
+        raise "Method#comment not supported by this Ruby version (#{RUBY_VERSION})"
       end
-      
-    ensure
-      file.close if file
+
+      comment
     end
   end
 end
diff --git a/lib/method_source/version.rb b/lib/method_source/version.rb
index 6461c90..2ac241c 100644
--- a/lib/method_source/version.rb
+++ b/lib/method_source/version.rb
@@ -1,3 +1,3 @@
 module MethodSource
-  VERSION = "0.1.4"
+  VERSION = "0.2.0"
 end
diff --git a/test/test.rb b/test/test.rb
index 05a711d..48f3ed8 100644
--- a/test/test.rb
+++ b/test/test.rb
@@ -2,17 +2,18 @@ direc = File.dirname(__FILE__)
 
 require 'bacon'
 require "#{direc}/../lib/method_source"
-
-hello_source = "def hello; :hello; end\n"
-lambda_source = "MyLambda = lambda { :lambda }\n"
-proc_source = "MyProc = Proc.new { :proc }\n"
-
-def hello; :hello; end
-
-MyLambda = lambda { :lambda }
-MyProc = Proc.new { :proc }
+require "#{direc}/test_helper"
 
 describe MethodSource do
+
+  before do
+    @hello_source = "def hello; :hello; end\n"
+    @hello_comment = "# A comment for hello\n# It spans two lines and is indented by 2 spaces\n"
+    @lambda_comment = "# This is a comment for MyLambda\n"
+    @lambda_source = "MyLambda = lambda { :lambda }\n"
+    @proc_source = "MyProc = Proc.new { :proc }\n"
+  end
+  
   it 'should define methods on Method and UnboundMethod and Proc' do
     Method.method_defined?(:source).should == true
     UnboundMethod.method_defined?(:source).should == true
@@ -22,7 +23,11 @@ describe MethodSource do
   describe "Methods" do
     if RUBY_VERSION =~ /1.9/
       it 'should return source for method' do
-        method(:hello).source.should == hello_source
+        method(:hello).source.should == @hello_source
+      end
+      
+      it 'should return a comment for method' do
+        method(:hello).comment.should == @hello_comment
       end
 
       it 'should raise for C methods' do
@@ -30,7 +35,7 @@ describe MethodSource do
       end
 
     else
-      it 'should raise on #source' do
+      it 'should raise on #source for 1.8' do
         lambda { method(:hello).source }.should.raise RuntimeError
       end
     end
@@ -39,16 +44,56 @@ describe MethodSource do
   describe "Lambdas and Procs" do
     if RUBY_VERSION =~ /1.9/
       it 'should return source for proc' do
-        MyProc.source.should == proc_source
+        MyProc.source.should == @proc_source
       end
-
+      
+      it 'should return an empty string if there is no comment' do
+        MyProc.comment.should == ''
+      end
+      
       it 'should return source for lambda' do
-        MyLambda.source.should == lambda_source
+        MyLambda.source.should == @lambda_source
+      end
+      
+      it 'should return comment for lambda' do
+        MyLambda.comment.should == @lambda_comment
       end
     else
-      it 'should raise on #source' do
+      it 'should raise on #source for 1.8' do
         lambda { method(:hello).source }.should.raise RuntimeError
       end
     end      
   end
+
+  if RUBY_VERSION =~ /1.9/
+    describe "Comment tests" do
+      before do
+        @comment1 = "# a\n# b\n"
+        @comment2 = "# a\n# b\n"
+        @comment3 = "# a\n#\n# b\n"
+        @comment4 = "# a\n# b\n"
+        @comment5 = "# a\n# b\n# c\n# d\n"
+      end
+
+      it "should correctly extract multi-line comments" do
+        method(:comment_test1).comment.should == @comment1
+      end
+
+      it "should correctly strip leading whitespace before comments" do
+        method(:comment_test2).comment.should == @comment2
+      end
+
+      it "should keep empty comment lines" do
+        method(:comment_test3).comment.should == @comment3
+      end
+      
+      it "should ignore blank lines between comments" do
+        method(:comment_test4).comment.should == @comment4
+      end
+
+      it "should align all comments to same indent level" do
+        method(:comment_test5).comment.should == @comment5
+      end      
+    end
+  end
 end
diff --git a/test/test_helper.rb b/test/test_helper.rb
new file mode 100644
index 0000000..78ef513
--- /dev/null
+++ b/test/test_helper.rb
@@ -0,0 +1,34 @@
+  # A comment for hello
+  
+  # It spans two lines and is indented by 2 spaces
+def hello; :hello; end
+
+# a
+# b
+def comment_test1; end
+
+ # a
+ # b
+def comment_test2; end
+
+# a
+#
+# b
+def comment_test3; end
+
+# a
+
+# b
+def comment_test4; end
+
+
+# a
+  # b
+    # c
+# d
+def comment_test5; end
+
+# This is a comment for MyLambda
+MyLambda = lambda { :lambda }
+MyProc = Proc.new { :proc }
+