RDoc::Parser::Ruby no longer skips over classes when the container's documentation is suppressed. This could place methods in the wrong class or attach them to Object. Issue #55

Add RDoc::CodeObject#ignore to facilitate hiding of classes via stopdoc

Author: drbrain

History.txt

@@ -6,6 +6,8 @@
   * `ri []` and other special methods now work properly.  Issue #52 by
     ddebernardy.
   * `ri` now has space between class comments from multiple files.
+  * The stopdoc directive no longer creates Object references.  Issue #55 by
+    Simon Chiang
 
 === 3.8 / 2011-06-29
 

lib/rdoc/code_object.rb

@@ -114,6 +114,7 @@ def initialize
     @done_documenting    = false
     @force_documentation = false
     @received_nodoc      = false
+    @ignored             = false
   end
 
   ##
@@ -139,6 +140,13 @@ def comment=(comment)
                end
   end
 
+  ##
+  # Should this CodeObject be shown in documentation?
+
+  def display?
+    @document_self and not @ignore
+  end
+
   ##
   # Enables or disables documentation of this CodeObject's children unless it
   # has been turned off by :enddoc:
@@ -195,6 +203,11 @@ def each_parent
     self
   end
 
+  ##
+  # File name where this CodeObject was found.
+  #
+  # See also RDoc::Context#in_files
+
   def file_name
     return unless @file
 
@@ -220,6 +233,34 @@ def full_name= full_name
     @full_name = full_name
   end
 
+  ##
+  # Use this to ignore a CodeObject and all its children until found again
+  # (#record_location is called).  An ignored item will not be shown in
+  # documentation.
+  #
+  # See github issue #55
+  #--
+  # The ignored status is temporary in order to allow implementation details
+  # to be hidden.  At the end of processing a file RDoc allows all classes
+  # and modules to add documentation.
+  #
+  # If a class was ignored (via stopdoc) then reopened later with additional
+  # documentation it should be shown.  If a class was ignored and never
+  # reopened it should not be shown.  The ignore flag allows this to occur.
+
+  def ignore
+    @ignored = true
+
+    stop_doc
+  end
+
+  ##
+  # Has this class been ignored?
+
+  def ignored?
+    @ignored
+  end
+
   ##
   # File name of our parent
 
@@ -238,6 +279,7 @@ def parent_name
   # Records the RDoc::TopLevel (file) where this code object was defined
 
   def record_location top_level
+    @ignored = false
     @file = top_level
   end
 
@@ -250,6 +292,7 @@ def start_doc
 
     @document_self = true
     @document_children = true
+    @ignored = false
   end
 
   ##

lib/rdoc/context.rb

@@ -423,6 +423,7 @@ def add_class class_type, given_name, superclass = '::Object'
     if klass then
       # if TopLevel, it may not be registered in the classes:
       enclosing.classes_hash[name] = klass
+
       # update the superclass if needed
       if superclass then
         existing = klass.superclass

lib/rdoc/generator/darkfish.rb

@@ -192,7 +192,7 @@ def get_sorted_module_list(classes)
       top_level = klass.full_name.gsub( /::.*/, '' )
       [nscounts[top_level] * -1, klass.full_name]
     end.select do |klass|
-      klass.document_self
+      klass.display?
     end
   end
 

lib/rdoc/parser/ruby.rb

@@ -611,6 +611,7 @@ def parse_class(container, single, tk, comment)
 
       cls_type = single == SINGLE ? RDoc::SingleClass : RDoc::NormalClass
       cls = declaration_context.add_class cls_type, given_name, superclass
+      cls.ignore unless container.document_children
 
       read_documentation_modifiers cls, RDoc::CLASS_MODIFIERS
       cls.record_location @top_level
@@ -1309,11 +1310,7 @@ def parse_statements(container, single = NORMAL, current_method = nil,
         keep_comment = true
 
       when TkCLASS then
-        if container.document_children then
-          parse_class container, single, tk, comment
-        else
-          nest += 1
-        end
+        parse_class container, single, tk, comment
 
       when TkMODULE then
         if container.document_children then
@@ -1504,6 +1501,7 @@ def parse_top_level_statements container
 
     # HACK move if to RDoc::Context#comment=
     container.comment = comment if container.document_self unless comment.empty?
+
     parse_statements container, NORMAL, nil, comment
   end
 

test/test_rdoc_code_object.rb

@@ -67,6 +67,26 @@ def test_comment_equals_encoding_blank
     assert_equal Encoding::UTF_8, @co.comment.encoding
   end
 
+  def test_display_eh_document_self
+    assert @co.display?
+
+    @co.stop_doc
+
+    refute @co.display?
+  end
+
+  def test_display_eh_ignore
+    assert @co.display?
+
+    @co.ignore
+
+    refute @co.display?
+
+    @co.stop_doc
+
+    refute @co.display?
+  end
+
   def test_document_children_equals
     @co.document_children = false
     refute @co.document_children
@@ -156,6 +176,22 @@ def test_full_name_equals
     assert_nil @co.instance_variable_get(:@full_name)
   end
 
+  def test_ignore
+    @co.ignore
+
+    refute @co.document_self
+    refute @co.document_children
+    assert @co.ignored?
+  end
+
+  def test_ignore_eh
+    refute @co.ignored?
+
+    @co.ignore
+
+    assert @co.ignored?
+  end
+
   def test_line
     @c1_m.line = 5
 
@@ -202,10 +238,16 @@ def test_received_ndoc
   end
 
   def test_record_location
-    c = RDoc::CodeObject.new
-    c.record_location @xref_data
+    @co.record_location @xref_data
+
+    assert_equal 'xref_data.rb', @co.file.relative_name
+  end
+
+  def test_record_location_ignored
+    @co.ignore
+    @co.record_location @xref_data
 
-    assert_equal 'xref_data.rb', c.file.relative_name
+    refute @co.ignored?
   end
 
   def test_start_doc
@@ -218,6 +260,16 @@ def test_start_doc
     assert @co.document_children
   end
 
+  def test_start_doc_ignored
+    @co.ignore
+
+    @co.start_doc
+
+    assert @co.document_self
+    assert @co.document_children
+    refute @co.ignored?
+  end
+
   def test_stop_doc
     @co.document_self = true
     @co.document_children = true

test/test_rdoc_generator_darkfish.rb

@@ -38,13 +38,17 @@ def setup
 
     @top_level = RDoc::TopLevel.new 'file.rb'
     @klass = @top_level.add_class RDoc::NormalClass, 'Object'
+
     @meth = RDoc::AnyMethod.new nil, 'method'
     @meth_bang = RDoc::AnyMethod.new nil, 'method!'
     @attr = RDoc::Attr.new nil, 'attr', 'RW', ''
 
     @klass.add_method @meth
     @klass.add_method @meth_bang
     @klass.add_attribute @attr
+
+    @ignored = @top_level.add_class RDoc::NormalClass, 'Ignored'
+    @ignored.ignore
   end
 
   def teardown
@@ -83,6 +87,8 @@ def test_generate
                  File.read('Object.html'))
     assert_match(/<meta content="text\/html; charset=#{encoding}"/,
                  File.read('file_rb.html'))
+
+    refute_match(/Ignored/, File.read('index.html'))
   end
 
   def test_generate_dry_run

test/test_rdoc_parser_ruby.rb

@@ -748,12 +748,7 @@ def test_parse_class_stopdoc
 
     @parser.parse_class @top_level, RDoc::Parser::Ruby::NORMAL, tk, comment
 
-    foo = @top_level.classes.first
-    assert_equal 'Foo', foo.full_name
-    assert_equal 'my class', foo.comment
-    assert_equal [@top_level], foo.in_files
-    assert_equal 0, foo.offset
-    assert_equal 1, foo.line
+    assert_empty @top_level.classes.first.comment
   end
 
   def test_parse_multi_ghost_methods
@@ -2178,6 +2173,26 @@ def test_parse_top_level_statements_stopdoc
     assert_empty @top_level.comment
   end
 
+  def test_parse_top_level_statements_stopdoc_integration
+    content = <<-CONTENT
+# :stopdoc:
+
+class Example
+  def method_name
+  end
+end
+    CONTENT
+
+    util_parser content
+
+    @parser.parse_top_level_statements @top_level
+
+    assert_equal 1, @top_level.classes.length
+    assert_empty @top_level.modules
+
+    assert @top_level.find_module_named('Example').ignored?
+  end
+
   def test_parse_yield_in_braces_with_parens
     klass = RDoc::NormalClass.new 'Foo'
     klass.parent = @top_level