rdoc 3.6.1 → 3.7

data/lib/rdoc/code_object.rb

@@ -130,7 +130,8 @@ class RDoc::CodeObject
                    # TODO is this sufficient?
                    # HACK correct fix is to have #initialize create @comment
                    #      with the correct encoding
-                   if Object.const_defined? :Encoding and @comment.empty? then
+                   if String === @comment and
+                      Object.const_defined? :Encoding and @comment.empty? then
                      @comment.force_encoding comment.encoding
                    end
                    @comment
@@ -194,6 +195,12 @@ class RDoc::CodeObject
     self
   end
 
+  def file_name
+    return unless @file
+
+    @file.absolute_name
+  end
+
   ##
   # Force the documentation of this object unless documentation
   # has been turned off by :endoc:

data/lib/rdoc/context.rb

@@ -30,9 +30,9 @@ class RDoc::Context < RDoc::CodeObject
   attr_reader :constants
 
   ##
-  # Current section of documentation
+  # Sets the current documentation section of documentation
 
-  attr_accessor :current_section
+  attr_writer :current_section
 
   ##
   # Files this context is found in
@@ -59,6 +59,11 @@ class RDoc::Context < RDoc::CodeObject
 
   attr_reader :requires
 
+  ##
+  # Use this section for the next method, attribute or constant added.
+
+  attr_accessor :temporary_section
+
   ##
   # Hash <tt>old_name => [aliases]</tt>, for aliases
   # that haven't (yet) been resolved to a method/attribute.
@@ -186,10 +191,7 @@ class RDoc::Context < RDoc::CodeObject
     end
 
     def inspect # :nodoc:
-      "#<%s:0x%x %s %p>" % [
-        self.class, object_id,
-        @sequence, title
-      ]
+      "#<%s:0x%x %p>" % [self.class, object_id, title]
     end
 
     ##
@@ -216,6 +218,7 @@ class RDoc::Context < RDoc::CodeObject
 
     @current_section = Section.new self, nil, nil
     @sections = { nil => @current_section }
+    @temporary_section = nil
 
     @classes = {}
     @modules = {}
@@ -287,22 +290,32 @@ class RDoc::Context < RDoc::CodeObject
     # TODO find a policy for 'attr_reader :foo' + 'def foo=()'
     register = false
 
-    if attribute.rw.index('R') then
+    key = nil
+
+    if attribute.rw.index 'R' then
       key = attribute.pretty_name
       known = @methods_hash[key]
+
       if known then
         known.comment = attribute.comment if known.comment.empty?
+      elsif registered = @methods_hash[attribute.pretty_name << '='] and
+            RDoc::Attr === registered then
+        registered.rw = 'RW'
       else
         @methods_hash[key] = attribute
         register = true
       end
     end
 
-    if attribute.rw.index('W')
+    if attribute.rw.index 'W' then
       key = attribute.pretty_name << '='
       known = @methods_hash[key]
+
       if known then
         known.comment = attribute.comment if known.comment.empty?
+      elsif registered = @methods_hash[attribute.pretty_name] and
+            RDoc::Attr === registered then
+        registered.rw = 'RW'
       else
         @methods_hash[key] = attribute
         register = true
@@ -314,6 +327,8 @@ class RDoc::Context < RDoc::CodeObject
       add_to @attributes, attribute
       resolve_aliases attribute
     end
+
+    attribute
   end
 
   ##
@@ -444,8 +459,8 @@ class RDoc::Context < RDoc::CodeObject
   # to +self+, and its #section to #current_section. Returns +mod+.
 
   def add_class_or_module mod, self_hash, all_hash
-    mod.section = @current_section # TODO declaring context? something is
-                                   # wrong here...
+    mod.section = current_section # TODO declaring context? something is
+                                  # wrong here...
     mod.parent = self
 
     unless @done_documenting then
@@ -462,7 +477,7 @@ class RDoc::Context < RDoc::CodeObject
   # Adds +constant+ if not already there. If it is, updates the comment,
   # value and/or is_alias_for of the known constant if they were empty/nil.
 
-  def add_constant(constant)
+  def add_constant constant
     return constant unless @document_self
 
     # HACK: avoid duplicate 'PI' & 'E' in math.c (1.8.7 source code)
@@ -480,28 +495,32 @@ class RDoc::Context < RDoc::CodeObject
       @constants_hash[constant.name] = constant
       add_to @constants, constant
     end
+
+    constant
   end
 
   ##
   # Adds included module +include+ which should be an RDoc::Include
 
-  def add_include(include)
-    add_to @includes, include unless @includes.map { |i| i.full_name }.include?( include.full_name )
+  def add_include include
+    add_to @includes, include unless
+      @includes.map { |i| i.full_name }.include? include.full_name
+
+    include
   end
 
   ##
   # Adds +method+ if not already there. If it is (as method or attribute),
   # updates the comment if it was empty.
 
-  def add_method(method)
+  def add_method method
     return method unless @document_self
 
     # HACK: avoid duplicate 'new' in io.c & struct.c (1.8.7 source code)
     key = method.pretty_name
     known = @methods_hash[key]
-    if known
-      # TODO issue stderr messages if --verbose
-      #$stderr.puts "\n#{display(method)} already registered as #{display(known)}"
+
+    if known then
       known.comment = method.comment if known.comment.empty?
     else
       @methods_hash[key] = method
@@ -509,6 +528,8 @@ class RDoc::Context < RDoc::CodeObject
       add_to @method_list, method
       resolve_aliases method
     end
+
+    method
   end
 
   ##
@@ -572,13 +593,32 @@ class RDoc::Context < RDoc::CodeObject
     end
   end
 
+  ##
+  # Returns a section with +title+, creating it if it doesn't already exist.
+  # +comment+ will be appended to the section's comment.
+  #
+  # A section with a +title+ of +nil+ will return the default section.
+  #
+  # See also RDoc::Context::Section
+
+  def add_section title, comment
+    if section = @sections[title] then
+      section.comment = comment
+    else
+      section = Section.new self, title, comment
+      @sections[title] = section
+    end
+
+    section
+  end
+
   ##
   # Adds +thing+ to the collection +array+
 
   def add_to(array, thing)
     array << thing if @document_self
     thing.parent = self
-    thing.section = @current_section
+    thing.section = current_section
   end
 
   ##
@@ -648,6 +688,20 @@ class RDoc::Context < RDoc::CodeObject
     @classes
   end
 
+  ##
+  # The current documentation section that new items will be added to.  If
+  # temporary_section is available it will be used.
+
+  def current_section
+    if section = @temporary_section then
+      @temporary_section = nil
+    else
+      section = @current_section
+    end
+
+    section
+  end
+
   ##
   # Is part of this thing was defined in +file+?
 
@@ -1082,18 +1136,10 @@ class RDoc::Context < RDoc::CodeObject
   end
 
   ##
-  # Creates a new section with +title+ and +comment+
-
-  def set_current_section(title, comment)
-    if @sections.key? title then
-      @current_section = @sections[title]
-      @current_section.comment = comment
-    else
-      @current_section = Section.new self, title, comment
-      @sections[title] = @current_section
-    end
+  # Sets the current section to a section with +title+.  See also #add_section
 
-    @current_section
+  def set_current_section title, comment
+    @current_section = add_section title, comment
   end
 
   ##

data/lib/rdoc/generator/markup.rb

@@ -42,7 +42,9 @@ module RDoc::Generator::Markup
     show_hash = RDoc::RDoc.current.options.show_hash
     hyperlink_all = RDoc::RDoc.current.options.hyperlink_all
     this = RDoc::Context === self ? self : @parent
-    @formatter = RDoc::Markup::ToHtmlCrossref.new this.path, this, show_hash, hyperlink_all
+
+    @formatter = RDoc::Markup::ToHtmlCrossref.new(this.path, this, show_hash,
+                                                  hyperlink_all)
   end
 
   ##

data/lib/rdoc/generator/ri.rb

@@ -18,11 +18,12 @@ class RDoc::Generator::RI
 
   def initialize options #:not-new:
     @options     = options
-    @store       = RDoc::RI::Store.new '.'
     @old_siginfo = nil
     @current     = nil
 
-    @store.dry_run = @options.dry_run
+    @store          = RDoc::RI::Store.new '.'
+    @store.dry_run  = @options.dry_run
+    @store.encoding = @options.encoding if @options.respond_to? :encoding
   end
 
   ##

data/lib/rdoc/generator/template/darkfish/rdoc.css

@@ -97,6 +97,10 @@ body.file p {
   margin: 1em 0;
 }
 
+.indexpage .rdoc-list p, .file .rdoc-list p {
+  margin: 0em 0;
+}
+
 .indexpage ol,
 .file #documentation ol {
   line-height: 160%;

data/lib/rdoc/known_classes.rb

@@ -36,7 +36,7 @@ module RDoc
     "rb_eArgError"         => "ArgError",
     "rb_eEOFError"         => "EOFError",
     "rb_eException"        => "Exception",
-    "rb_eFatal"            => "Fatal",
+    "rb_eFatal"            => "fatal",
     "rb_eFloatDomainError" => "FloatDomainError",
     "rb_eIOError"          => "IOError",
     "rb_eIndexError"       => "IndexError",
@@ -49,7 +49,7 @@ module RDoc
     "rb_eRuntimeError"     => "RuntimeError",
     "rb_eScriptError"      => "ScriptError",
     "rb_eSecurityError"    => "SecurityError",
-    "rb_eSignal"           => "Signal",
+    "rb_eSignal"           => "SignalException",
     "rb_eStandardError"    => "StandardError",
     "rb_eSyntaxError"      => "SyntaxError",
     "rb_eSystemCallError"  => "SystemCallError",

data/lib/rdoc/markup.rb

@@ -48,13 +48,13 @@ require 'rdoc'
 #     end
 #   end
 #
-#   m = RDoc::Markup.new
-#   m.add_word_pair("{", "}", :STRIKE)
-#   m.add_html("no", :STRIKE)
+#   markup = RDoc::Markup.new
+#   markup.add_word_pair("{", "}", :STRIKE)
+#   markup.add_html("no", :STRIKE)
 #
-#   m.add_special(/\b([A-Z][a-z]+[A-Z]\w+)/, :WIKIWORD)
+#   markup.add_special(/\b([A-Z][a-z]+[A-Z]\w+)/, :WIKIWORD)
 #
-#   wh = WikiHtml.new
+#   wh = WikiHtml.new markup
 #   wh.add_tag(:STRIKE, "<strike>", "</strike>")
 #
 #   puts "<body>#{wh.convert ARGF.read}</body>"
@@ -498,15 +498,53 @@ require 'rdoc'
 # [+:main:+ _name_]
 #   Equivalent to the <tt>--main</tt> command line parameter.
 #
+# [<tt>:category: section</tt>]
+#   Adds this item to the named +section+ overriding the current section.  Use
+#   this to group methods by section in RDoc output while maintaining a
+#   sensible ordering (like alphabetical).
+#
+#     # :category: Utility Methods
+#     #
+#     # CGI escapes +text+
+#
+#     def convert_string text
+#       CGI.escapeHTML text
+#     end
+#
+#   An empty category will place the item in the default category:
+#
+#     # :category:
+#     #
+#     # This method is in the default category
+#
+#     def some_method
+#       # ...
+#     end
+#
+#   Unlike the :section: directive, :category: is not sticky.  The category
+#   only applies to the item immediately following the comment.
+#
+#   Use the :section: directive to provide introductory text for a section of
+#   documentation.
+#
 # [<tt>:section: title</tt>]
-#   Starts a new section in the output.  The title following +:section:+ is
-#   used as the section heading, and the remainder of the comment containing
-#   the section is used as introductory text.  Subsequent methods, aliases,
-#   attributes, and classes will be documented in this section.
+#   Provides section introductory text in RDoc output.  The title following
+#   +:section:+ is used as the section name and the remainder of the comment
+#   containing the section is used as introductory text.  A section's comment
+#   block must be separated from following comment blocks.  Use an empty title
+#   to switch to the default section.
+#
+#   The :section: directive is sticky, so subsequent methods, aliases,
+#   attributes, and classes will be contained in this section until the
+#   section is changed.  The :category: directive will override the :section:
+#   directive.
 #
 #   A :section: comment block may have one or more lines before the :section:
 #   directive.  These will be removed, and any identical lines at the end of
-#   the block are also removed.  This allows you to add visual cues such as:
+#   the block are also removed.  This allows you to add visual cues to the
+#   section.
+#
+#   Example:
 #
 #     # ----------------------------------------
 #     # :section: My Section
@@ -514,10 +552,12 @@ require 'rdoc'
 #     # See it glisten in the noon-day sun.
 #     # ----------------------------------------
 #
-#   Sections may be referenced multiple times in a class or module allowing
-#   methods, attributes and constants to be ordered one way for implementation
-#   ordering but still grouped together in documentation.  If a section has
-#   multiple comments they will be concatenated with a dividing rule.
+#     ##
+#     # Comment for some_method
+#
+#     def some_method
+#       # ...
+#     end
 #
 # [+:call-seq:+]
 #   Lines up to the next blank line in the comment are treated as the method's
@@ -576,11 +616,16 @@ class RDoc::Markup
   end
 
   ##
-  # We take +text+, parse it then invoke the output +formatter+ using a
-  # Visitor to render the result.
+  # We take +input+, parse it if necessary, then invoke the output +formatter+
+  # using a Visitor to render the result.
 
-  def convert text, formatter
-    document = RDoc::Markup::Parser.parse text
+  def convert input, formatter
+    document = case input
+               when RDoc::Markup::Document then
+                 input
+               else
+                 RDoc::Markup::Parser.parse input
+               end
 
     document.accept formatter
   end

data/lib/rdoc/markup/document.rb

@@ -3,6 +3,12 @@
 
 class RDoc::Markup::Document
 
+  ##
+  # The file this document was created from.  See also
+  # RDoc::ClassModule#add_comment
+
+  attr_accessor :file
+
   ##
   # The parts of the Document
 
@@ -14,6 +20,8 @@ class RDoc::Markup::Document
   def initialize *parts
     @parts = []
     @parts.push(*parts)
+
+    @file = nil
   end
 
   ##
@@ -36,7 +44,9 @@ class RDoc::Markup::Document
   end
 
   def == other # :nodoc:
-    self.class == other.class and @parts == other.parts
+    self.class == other.class and
+      @file == other.file and
+      @parts == other.parts
   end
 
   ##
@@ -46,7 +56,12 @@ class RDoc::Markup::Document
     visitor.start_accepting
 
     @parts.each do |item|
-      item.accept visitor
+      case item
+      when RDoc::Markup::Document then # HACK
+        visitor.accept_document item
+      else
+        item.accept visitor
+      end
     end
 
     visitor.end_accepting
@@ -56,11 +71,35 @@ class RDoc::Markup::Document
   # Does this document have no parts?
 
   def empty?
-    @parts.empty?
+    @parts.empty? or
+      (@parts.length == 1 and RDoc::Markup::Document === @parts.first and
+       @parts.first.empty?)
+  end
+
+  ##
+  # When this is a collection of documents (#file is not set and this document
+  # contains only other documents as its direct children) #merge replaces
+  # documents in this class with documents from +other+ when the file matches
+  # and adds documents from +other+ when the files do not.
+  #
+  # The information in +other+ is preferred over the receiver
+
+  def merge other
+    other.parts.each do |other_part|
+      self.parts.delete_if do |self_part|
+        self_part.file and self_part.file == other_part.file
+      end
+
+      self.parts << other_part
+    end
+
+    self
   end
 
   def pretty_print q # :nodoc:
-    q.group 2, '[doc: ', ']' do
+    start = @file ? "[doc (#{@file}): " : '[doc: '
+
+    q.group 2, start, ']' do
       q.seplist @parts do |part|
         q.pp part
       end