Add :attr*: directives to the ruby parser.

Author: drbrain

History.txt

@@ -1,5 +1,9 @@
 === 2.4.1 / ??
 
+* N Minor Enhancements
+  * Added :attr:, :attr_reader:, :attr_writer:, :attr_accessor: directives.
+    See RDoc::Parser::Ruby for details.
+
 * N Bug Fixes
   * Don't complain when exiting normally.  Bug by Matt Neuburg.
   * Restore --inline-source that warns.

lib/rdoc/parser/ruby.rb

@@ -1439,12 +1439,23 @@ def read_escape
 #   ##
 #   # :singleton-method: woo_hoo!
 #
-# == Hidden methods
+# Additionally you can mark a method as an attribute by using :attr:,
+# :attr_reader:, :attr_writer: or :attr_accessor:.  Just like for :method:,
+# the name is optional.
+#
+#   ##
+#   # :attr_reader: my_attr_name
+#
+# == Hidden methods and attributes
 #
 # You can provide documentation for methods that don't appear using
-# the :method: and :singleton-method: directives:
+# the :method:, :singleton-method: and :attr: directives:
 #
 #   ##
+#   # :attr_writer: ghost_writer
+#   # There is an attribute here, but you can't see it!
+#   
+#   ##
 #   # :method: ghost_method
 #   # There is a method here, but you can't see it!
 #   
@@ -1765,8 +1776,12 @@ def make_message(msg)
     return prefix + msg
   end
 
+  ##
+  # Creates an RDoc::Attr for the name following +tk+, setting the comment to
+  # +comment+.
+
   def parse_attr(context, single, tk, comment)
-    args = parse_symbol_arg(1)
+    args = parse_symbol_arg 1
     if args.size > 0
       name = args[0]
       rw = "R"
@@ -1787,12 +1802,16 @@ def parse_attr(context, single, tk, comment)
     end
   end
 
+  ##
+  # Creates an RDoc::Attr for each attribute listed after +tk+, setting the
+  # comment for each to +comment+.
+
   def parse_attr_accessor(context, single, tk, comment)
     args = parse_symbol_arg
     read = get_tkread
     rw = "?"
 
-    # If nodoc is given, don't document any of them
+    # TODO If nodoc is given, don't document any of them
 
     tmp = RDoc::CodeObject.new
     read_documentation_modifiers tmp, RDoc::ATTR_MODIFIERS
@@ -1973,37 +1992,51 @@ def parse_constant(container, single, tk, comment)
     end
   end
 
+  ##
+  # Generates an RDoc::Method or RDoc::Attr from +comment+ by looking for
+  # :method: or :attr: directives in +comment+.
+
   def parse_comment(container, tk, comment)
     line_no = tk.line_no
     column  = tk.char_no
 
     singleton = !!comment.sub!(/(^# +:?)(singleton-)(method:)/, '\1\3')
 
+    # REFACTOR
     if comment.sub!(/^# +:?method: *(\S*).*?\n/i, '') then
       name = $1 unless $1.empty?
-    else
-      return nil
-    end
 
-    meth = RDoc::GhostMethod.new get_tkread, name
-    meth.singleton = singleton
+      meth = RDoc::GhostMethod.new get_tkread, name
+      meth.singleton = singleton
 
-    @stats.add_method meth
+      @stats.add_method meth
 
-    meth.start_collecting_tokens
-    indent = TkSPACE.new 1, 1
-    indent.set_text " " * column
+      meth.start_collecting_tokens
+      indent = TkSPACE.new 1, 1
+      indent.set_text " " * column
 
-    position_comment = TkCOMMENT.new(line_no, 1, "# File #{@top_level.absolute_name}, line #{line_no}")
-    meth.add_tokens [position_comment, NEWLINE_TOKEN, indent]
+      position_comment = TkCOMMENT.new(line_no, 1, "# File #{@top_level.absolute_name}, line #{line_no}")
+      meth.add_tokens [position_comment, NEWLINE_TOKEN, indent]
 
-    meth.params = ''
+      meth.params = ''
 
-    extract_call_seq comment, meth
+      extract_call_seq comment, meth
 
-    container.add_method meth if meth.document_self
+      container.add_method meth if meth.document_self
 
-    meth.comment = comment
+      meth.comment = comment
+    elsif comment.sub!(/# +:?(attr(_reader|_writer|_accessor)?:) *(\S*).*?\n/i, '') then
+      rw = case $1
+           when 'attr_reader' then 'R'
+           when 'attr_writer' then 'W'
+           else 'RW'
+           end
+
+      name = $3 unless $3.empty?
+
+      att = RDoc::Attr.new get_tkread, name, rw, comment
+      container.add_attribute att
+    end
   end
 
   def parse_include(context, comment)
@@ -2018,6 +2051,32 @@ def parse_include(context, comment)
     end
   end
 
+  def parse_meta_attr(context, single, tk, comment)
+    args = parse_symbol_arg
+    read = get_tkread
+    rw = "?"
+
+    # If nodoc is given, don't document any of them
+
+    tmp = RDoc::CodeObject.new
+    read_documentation_modifiers tmp, RDoc::ATTR_MODIFIERS
+    return unless tmp.document_self
+
+    if comment.sub!(/^# +:?(attr(_reader|_writer|_accessor)?): *(\S*).*?\n/i, '') then
+      rw = case $1
+           when 'attr_reader' then 'R'
+           when 'attr_writer' then 'W'
+           else 'RW'
+           end
+      name = $3 unless $3.empty?
+    end
+
+    for name in args
+      att = RDoc::Attr.new get_tkread, name, rw, comment
+      context.add_attribute att
+    end
+  end
+
   ##
   # Parses a meta-programmed method
 

test/test_rdoc_parser_ruby.rb

@@ -28,6 +28,28 @@ def teardown
     @tempfile2.close
   end
 
+  def test_look_for_directives_in_attr
+    util_parser ""
+
+    comment = "# :attr: my_attr\n"
+
+    @parser.look_for_directives_in @top_level, comment
+
+    assert_equal "# :attr: my_attr\n", comment
+
+    comment = "# :attr_reader: my_method\n"
+
+    @parser.look_for_directives_in @top_level, comment
+
+    assert_equal "# :attr_reader: my_method\n", comment
+
+    comment = "# :attr_writer: my_method\n"
+
+    @parser.look_for_directives_in @top_level, comment
+
+    assert_equal "# :attr_writer: my_method\n", comment
+  end
+
   def test_look_for_directives_in_commented
     util_parser ""
 
@@ -136,6 +158,147 @@ def test_look_for_directives_in_unhandled
     assert_equal 'hi', @options.title
   end
 
+  def test_parse_attr
+    klass = RDoc::NormalClass.new 'Foo'
+    klass.parent = @top_level
+
+    comment = "##\n# my attr\n"
+
+    util_parser "attr :foo, :bar"
+
+    tk = @parser.get_tk
+
+    @parser.parse_attr klass, RDoc::Parser::Ruby::NORMAL, tk, comment
+
+    assert_equal 1, klass.attributes.length
+
+    foo = klass.attributes.first
+    assert_equal 'foo', foo.name
+    assert_equal "##\n# my attr\n", foo.comment
+  end
+
+  def test_parse_attr_accessor
+    klass = RDoc::NormalClass.new 'Foo'
+    klass.parent = @top_level
+
+    comment = "##\n# my attr\n"
+
+    util_parser "attr_accessor :foo, :bar"
+
+    tk = @parser.get_tk
+
+    @parser.parse_attr_accessor klass, RDoc::Parser::Ruby::NORMAL, tk, comment
+
+    assert_equal 2, klass.attributes.length
+
+    foo = klass.attributes.first
+    assert_equal 'foo', foo.name
+    assert_equal 'RW', foo.rw
+    assert_equal "##\n# my attr\n", foo.comment
+
+    bar = klass.attributes.last
+    assert_equal 'bar', bar.name
+    assert_equal 'RW', bar.rw
+    assert_equal "##\n# my attr\n", bar.comment
+  end
+
+  def test_parse_attr_accessor_writer
+    klass = RDoc::NormalClass.new 'Foo'
+    klass.parent = @top_level
+
+    comment = "##\n# my attr\n"
+
+    util_parser "attr_writer :foo, :bar"
+
+    tk = @parser.get_tk
+
+    @parser.parse_attr_accessor klass, RDoc::Parser::Ruby::NORMAL, tk, comment
+
+    assert_equal 2, klass.attributes.length
+
+    foo = klass.attributes.first
+    assert_equal 'foo', foo.name
+    assert_equal 'W', foo.rw
+    assert_equal "##\n# my attr\n", foo.comment
+
+    bar = klass.attributes.last
+    assert_equal 'bar', bar.name
+    assert_equal 'W', bar.rw
+    assert_equal "##\n# my attr\n", bar.comment
+  end
+
+  def test_parse_meta_attr
+    klass = RDoc::NormalClass.new 'Foo'
+    klass.parent = @top_level
+
+    comment = "##\n# :attr: \n# my method\n"
+
+    util_parser "add_my_method :foo, :bar"
+
+    tk = @parser.get_tk
+
+    @parser.parse_meta_attr klass, RDoc::Parser::Ruby::NORMAL, tk, comment
+
+    foo = klass.attributes.first
+    assert_equal 'foo', foo.name
+    assert_equal 'RW', foo.rw
+    assert_equal "##\n# my method\n", foo.comment
+  end
+
+  def test_parse_meta_attr_accessor
+    klass = RDoc::NormalClass.new 'Foo'
+    klass.parent = @top_level
+
+    comment = "##\n# :attr_accessor: \n# my method\n"
+
+    util_parser "add_my_method :foo, :bar"
+
+    tk = @parser.get_tk
+
+    @parser.parse_meta_attr klass, RDoc::Parser::Ruby::NORMAL, tk, comment
+
+    foo = klass.attributes.first
+    assert_equal 'foo', foo.name
+    assert_equal 'RW', foo.rw
+    assert_equal "##\n# my method\n", foo.comment
+  end
+
+  def test_parse_meta_attr_reader
+    klass = RDoc::NormalClass.new 'Foo'
+    klass.parent = @top_level
+
+    comment = "##\n# :attr_reader: \n# my method\n"
+
+    util_parser "add_my_method :foo, :bar"
+
+    tk = @parser.get_tk
+
+    @parser.parse_meta_attr klass, RDoc::Parser::Ruby::NORMAL, tk, comment
+
+    foo = klass.attributes.first
+    assert_equal 'foo', foo.name
+    assert_equal 'R', foo.rw
+    assert_equal "##\n# my method\n", foo.comment
+  end
+
+  def test_parse_meta_attr_writer
+    klass = RDoc::NormalClass.new 'Foo'
+    klass.parent = @top_level
+
+    comment = "##\n# :attr_writer: \n# my method\n"
+
+    util_parser "add_my_method :foo, :bar"
+
+    tk = @parser.get_tk
+
+    @parser.parse_meta_attr klass, RDoc::Parser::Ruby::NORMAL, tk, comment
+
+    foo = klass.attributes.first
+    assert_equal 'foo', foo.name
+    assert_equal 'W', foo.rw
+    assert_equal "##\n# my method\n", foo.comment
+  end
+
   def test_parse_class
     comment = "##\n# my method\n"
 
@@ -265,15 +428,35 @@ class Helper
     assert_equal 'Foo::Helper', helper.full_name
   end
 
-  def test_parse_comment
-    content = <<-EOF
-class Foo
-  ##
-  # :method: my_method
-  # my method comment
+  def test_parse_comment_attr
+    klass = RDoc::NormalClass.new 'Foo'
+    klass.parent = @top_level
 
-end
-    EOF
+    comment = "##\n# :attr: foo\n# my attr\n"
+
+    util_parser "\n"
+
+    tk = @parser.get_tk
+
+    @parser.parse_comment klass, tk, comment
+
+    foo = klass.attributes.first
+    assert_equal 'foo',     foo.name
+    assert_equal 'RW',      foo.rw
+    assert_equal comment,   foo.comment
+
+    assert_equal nil,       foo.viewer
+    assert_equal true,      foo.document_children
+    assert_equal true,      foo.document_self
+    assert_equal false,     foo.done_documenting
+    assert_equal false,     foo.force_documentation
+    assert_equal klass,     foo.parent
+    assert_equal :public,   foo.visibility
+    assert_equal "\n",      foo.text
+    assert_equal klass.current_section, foo.section
+  end
+
+  def test_parse_comment_method
     klass = RDoc::NormalClass.new 'Foo'
     klass.parent = @top_level