rdoc 4.0.1 → 4.1.0.preview.3

data/Rakefile

@@ -46,11 +46,13 @@ Depending on your version of ruby, you may need to install ruby rdoc/ri data:
   self.history_file = 'History.rdoc'
   self.testlib = :minitest
   self.extra_rdoc_files += %w[
-    DEVELOPERS.rdoc
     CVE-2013-0256.rdoc
+    CONTRIBUTING.rdoc
+    ExampleMarkdown.md
+    ExampleRDoc.rdoc
     History.rdoc
-    LICENSE.rdoc
     LEGAL.rdoc
+    LICENSE.rdoc
     README.rdoc
     RI.rdoc
     TODO.rdoc
@@ -61,15 +63,43 @@ Depending on your version of ruby, you may need to install ruby rdoc/ri data:
 
   require_ruby_version '>= 1.8.7'
   extra_deps     << ['json',     '~> 1.4']
-  extra_dev_deps << ['racc',     '~> 1.4']
+  extra_dev_deps << ['racc',     '~> 1.4', '!= 1.4.10']
   extra_dev_deps << ['minitest', '~> 4']
-  extra_dev_deps << ['ZenTest',  '~> 4']
 
   extra_rdoc_files << 'Rakefile'
   spec_extras['required_rubygems_version'] = '>= 1.3'
   spec_extras['homepage'] = 'http://docs.seattlerb.org/rdoc'
 end
 
+hoe.test_prelude = 'gem "minitest", "~> 4.0"'
+
+def rake(*args)
+  sh $0, *args
+end
+
+if PARSER_FILES.any? {|file| not File.exist?(file)}
+  Rake::Task["default"].prerequisites.clear
+  task :default do
+    rake "install_plugins"
+    rake "newb"
+  end
+end
+
+Rake::Task['docs'].actions.clear
+task :docs do
+  $LOAD_PATH.unshift 'lib'
+  require 'rdoc'
+
+  options = RDoc::Options.new
+  options.title = "rdoc #{RDoc::VERSION} Documentation"
+  options.op_dir = 'doc'
+  options.main_page = 'README.rdoc'
+  options.files = hoe.spec.extra_rdoc_files + %w[lib]
+  options.setup_generator 'darkfish'
+
+  RDoc::RDoc.new.document options
+end
+
 # requires ruby 1.8 and ruby 1.8 to build
 hoe.clean_globs -= PARSER_FILES.grep(/literals_/)
 

data/lib/rdoc.rb

@@ -14,7 +14,7 @@ $DEBUG_RDOC = nil
 #
 # == Roadmap
 #
-# If you think you found a bug in RDoc see DEVELOPERS@Bugs
+# If you think you found a bug in RDoc see CONTRIBUTING@Bugs
 #
 # If you want to use RDoc to create documentation for your Ruby source files,
 # see RDoc::Markup and refer to <tt>rdoc --help</tt> for command line usage.
@@ -42,7 +42,7 @@ $DEBUG_RDOC = nil
 #
 # If you want to write your own output generator see RDoc::Generator.
 #
-# If you want an overview of how RDoc works see DEVELOPERS
+# If you want an overview of how RDoc works see CONTRIBUTING
 #
 # == Credits
 #
@@ -64,7 +64,7 @@ module RDoc
   ##
   # RDoc version you are using
 
-  VERSION = '4.0.1'
+  VERSION = '4.1.0.preview.3'
 
   ##
   # Method visibilities
@@ -174,6 +174,7 @@ module RDoc
   autoload :Attr,           'rdoc/attr'
 
   autoload :Constant,       'rdoc/constant'
+  autoload :Mixin,          'rdoc/mixin'
   autoload :Include,        'rdoc/include'
   autoload :Extend,         'rdoc/extend'
   autoload :Require,        'rdoc/require'

data/lib/rdoc/any_method.rb

@@ -9,8 +9,11 @@ class RDoc::AnyMethod < RDoc::MethodAttr
   #   Added calls_super
   #   Added parent name and class
   #   Added section title
+  # 3::
+  #   RDoc 4.1
+  #   Added is_alias_for
 
-  MARSHAL_VERSION = 2 # :nodoc:
+  MARSHAL_VERSION = 3 # :nodoc:
 
   ##
   # Don't rename \#initialize to \::new
@@ -25,7 +28,7 @@ class RDoc::AnyMethod < RDoc::MethodAttr
   ##
   # Different ways to call this method
 
-  attr_accessor :call_seq
+  attr_reader :call_seq
 
   ##
   # Parameters for this method
@@ -89,6 +92,37 @@ class RDoc::AnyMethod < RDoc::MethodAttr
     end
   end
 
+  ##
+  # Sets the different ways you can call this method.  If an empty +call_seq+
+  # is given nil is assumed.
+  #
+  # See also #param_seq
+
+  def call_seq= call_seq
+    return if call_seq.empty?
+
+    @call_seq = call_seq
+  end
+
+  ##
+  # Loads is_alias_for from the internal name.  Returns nil if the alias
+  # cannot be found.
+
+  def is_alias_for # :nodoc:
+    case @is_alias_for
+    when RDoc::MethodAttr then
+      @is_alias_for
+    when Array then
+      return nil unless @store
+
+      klass_name, singleton, method_name = @is_alias_for
+
+      return nil unless klass = @store.find_class_or_module(klass_name)
+
+      @is_alias_for = klass.find_method method_name, singleton
+    end
+  end
+
   ##
   # Dumps this AnyMethod for use by ri.  See also #marshal_load
 
@@ -97,6 +131,12 @@ class RDoc::AnyMethod < RDoc::MethodAttr
       [a.name, parse(a.comment)]
     end
 
+    is_alias_for = [
+      @is_alias_for.parent.full_name,
+      @is_alias_for.singleton,
+      @is_alias_for.name
+    ] if @is_alias_for
+
     [ MARSHAL_VERSION,
       @name,
       full_name,
@@ -112,6 +152,7 @@ class RDoc::AnyMethod < RDoc::MethodAttr
       @parent.name,
       @parent.class,
       @section.title,
+      is_alias_for,
     ]
   end
 
@@ -126,7 +167,6 @@ class RDoc::AnyMethod < RDoc::MethodAttr
     initialize_visibility
 
     @dont_rename_initialize = nil
-    @is_alias_for           = nil
     @token_stream           = nil
     @aliases                = []
     @parent                 = nil
@@ -150,6 +190,7 @@ class RDoc::AnyMethod < RDoc::MethodAttr
     @parent_name   = array[12]
     @parent_title  = array[13]
     @section_title = array[14]
+    @is_alias_for  = array[15]
 
     array[8].each do |new_name, comment|
       add_alias RDoc::Alias.new(nil, @name, new_name, comment, @singleton)
@@ -174,7 +215,10 @@ class RDoc::AnyMethod < RDoc::MethodAttr
   def name
     return @name if @name
 
-    @name = @call_seq[/^.*?\.(\w+)/, 1] || @call_seq if @call_seq
+    @name =
+      @call_seq[/^.*?\.(\w+)/, 1] ||
+      @call_seq[/^.*?(\w+)/, 1] ||
+      @call_seq if @call_seq
   end
 
   ##

data/lib/rdoc/class_module.rb

@@ -169,13 +169,25 @@ class RDoc::ClassModule < RDoc::Context
     includes.map { |i| i.module }.reverse
   end
 
+  def aref_prefix # :nodoc:
+    raise NotImplementedError, "missing aref_prefix for #{self.class}"
+  end
+
+  ##
+  # HTML fragment reference for this module or class.  See
+  # RDoc::NormalClass#aref and RDoc::NormalModule#aref
+
+  def aref
+    "#{aref_prefix}-#{full_name}"
+  end
+
   ##
   # Ancestors of this class or module only
 
   alias direct_ancestors ancestors
 
   ##
-  # Clears the comment. Used by the ruby parser.
+  # Clears the comment. Used by the Ruby parser.
 
   def clear_comment
     @comment = ''
@@ -224,7 +236,9 @@ class RDoc::ClassModule < RDoc::Context
   # #received_nodoc true?
 
   def documented?
-    super or !@comment_location.empty?
+    return true if @received_nodoc
+    return false if @comment_location.empty?
+    @comment_location.any? { |comment, _| not comment.empty? }
   end
 
   ##

data/lib/rdoc/code_object.rb

@@ -20,8 +20,9 @@
 #     * RDoc::MetaMethod
 # * RDoc::Alias
 # * RDoc::Constant
-# * RDoc::Require
-# * RDoc::Include
+# * RDoc::Mixin
+#   * RDoc::Require
+#   * RDoc::Include
 
 class RDoc::CodeObject
 
@@ -92,7 +93,7 @@ class RDoc::CodeObject
   ##
   # The RDoc::Store for this object.
 
-  attr_accessor :store
+  attr_reader :store
 
   ##
   # We are the model of the code, but we know that at some point we will be
@@ -105,16 +106,17 @@ class RDoc::CodeObject
   # Creates a new CodeObject that will document itself and its children
 
   def initialize
-    @metadata      = {}
-    @comment       = ''
-    @parent        = nil
-    @parent_name   = nil # for loading
-    @parent_class  = nil # for loading
-    @section       = nil
-    @section_title = nil # for loading
-    @file          = nil
-    @full_name     = nil
-    @store         = nil
+    @metadata         = {}
+    @comment          = ''
+    @parent           = nil
+    @parent_name      = nil # for loading
+    @parent_class     = nil # for loading
+    @section          = nil
+    @section_title    = nil # for loading
+    @file             = nil
+    @full_name        = nil
+    @store            = nil
+    @track_visibility = true
 
     initialize_visibility
   end
@@ -129,6 +131,8 @@ class RDoc::CodeObject
     @force_documentation = false
     @received_nodoc      = false
     @ignored             = false
+    @suppressed          = false
+    @track_visibility    = true
   end
 
   ##
@@ -155,10 +159,17 @@ class RDoc::CodeObject
   end
 
   ##
-  # Should this CodeObject be shown in documentation?
+  # Should this CodeObject be displayed in output?
+  #
+  # A code object should be displayed if:
+  #
+  # * The item didn't have a nodoc or wasn't in a container that had nodoc
+  # * The item wasn't ignored
+  # * The item has documentation and was not suppressed
 
   def display?
-    @document_self and not @ignored
+    @document_self and not @ignored and
+      (documented? or not @suppressed)
   end
 
   ##
@@ -166,6 +177,8 @@ class RDoc::CodeObject
   # has been turned off by :enddoc:
 
   def document_children=(document_children)
+    return unless @track_visibility
+
     @document_children = document_children unless @done_documenting
   end
 
@@ -175,6 +188,7 @@ class RDoc::CodeObject
   # documentation is turned off by +:nodoc:+.
 
   def document_self=(document_self)
+    return unless @track_visibility
     return if @done_documenting
 
     @document_self = document_self
@@ -198,8 +212,9 @@ class RDoc::CodeObject
   # will have no effect in the current file.
 
   def done_documenting=(value)
-    @done_documenting = value
-    @document_self = !value
+    return unless @track_visibility
+    @done_documenting  = value
+    @document_self     = !value
     @document_children = @document_self
   end
 
@@ -249,7 +264,7 @@ class RDoc::CodeObject
 
   ##
   # 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
+  # (#record_location is called).  An ignored item will not be displayed in
   # documentation.
   #
   # See github issue #55
@@ -259,10 +274,13 @@ class RDoc::CodeObject
   # and modules to add new documentation to previously created classes.
   #
   # 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.
+  # documentation it should be displayed.  If a class was ignored and never
+  # reopened it should not be displayed.  The ignore flag allows this to
+  # occur.
 
   def ignore
+    return unless @track_visibility
+
     @ignored = true
 
     stop_doc
@@ -270,6 +288,8 @@ class RDoc::CodeObject
 
   ##
   # Has this class been ignored?
+  #
+  # See also #ignore
 
   def ignored?
     @ignored
@@ -282,7 +302,7 @@ class RDoc::CodeObject
   # This is used by Text#snippet
 
   def options
-    if @store then
+    if @store and @store.rdoc then
       @store.rdoc.options
     else
       RDoc::Options.new
@@ -330,8 +350,9 @@ class RDoc::CodeObject
   # Records the RDoc::TopLevel (file) where this code object was defined
 
   def record_location top_level
-    @ignored = false
-    @file = top_level
+    @ignored    = false
+    @suppressed = false
+    @file       = top_level
   end
 
   ##
@@ -353,16 +374,56 @@ class RDoc::CodeObject
 
     @document_self = true
     @document_children = true
-    @ignored = false
+    @ignored    = false
+    @suppressed = false
   end
 
   ##
   # Disable capture of documentation
 
   def stop_doc
+    return unless @track_visibility
+
     @document_self = false
     @document_children = false
   end
 
+  ##
+  # Sets the +store+ that contains this CodeObject
+
+  def store= store
+    @store = store
+
+    return unless @track_visibility
+
+    if :nodoc == options.visibility then
+      initialize_visibility
+      @track_visibility = false
+    end
+  end
+
+  ##
+  # Use this to suppress a CodeObject and all its children until the next file
+  # it is seen in or documentation is discovered.  A suppressed item with
+  # documentation will be displayed while an ignored item with documentation
+  # may not be displayed.
+
+  def suppress
+    return unless @track_visibility
+
+    @suppressed = true
+
+    stop_doc
+  end
+
+  ##
+  # Has this class been suppressed?
+  #
+  # See also #suppress
+
+  def suppressed?
+    @suppressed
+  end
+
 end