rdoc 4.0.0.preview2 → 4.0.0.preview2.1

data/lib/rdoc/parser/c.rb

@@ -122,6 +122,11 @@ class RDoc::Parser::C < RDoc::Parser
 
   include RDoc::Text
 
+  ##
+  # Maps C variable names to names of ruby classes or modules
+
+  attr_reader :classes
+
   ##
   # C file the parser is parsing
 
@@ -150,16 +155,23 @@ class RDoc::Parser::C < RDoc::Parser
   attr_reader :singleton_classes
 
   ##
-  # Prepare to parse a C file
+  # The TopLevel items in the parsed file belong to
+
+  attr_reader :top_level
+
+  ##
+  # Prepares for parsing a C file.  See RDoc::Parser#initialize for details on
+  # the arguments.
 
-  def initialize(top_level, file_name, content, options, stats)
+  def initialize top_level, file_name, content, options, stats
     super
 
     @known_classes = RDoc::KNOWN_CLASSES.dup
-    @content = handle_tab_width handle_ifdefs_in(@content)
-    @classes = {}
-    @singleton_classes = {}
-    @file_dir = File.dirname(@file_name)
+    @content = handle_tab_width handle_ifdefs_in @content
+    @file_dir = File.dirname @file_name
+
+    @classes           = load_variable_map :c_class_variables
+    @singleton_classes = load_variable_map :c_singleton_class_variables
 
     # missing variable => [handle_class_module arguments]
     @missing_dependencies = {}
@@ -386,13 +398,12 @@ class RDoc::Parser::C < RDoc::Parser
 
   def do_includes
     @content.scan(/rb_include_module\s*\(\s*(\w+?),\s*(\w+?)\s*\)/) do |c,m|
-      if cls = @classes[c]
-        m = @known_classes[m] || m
+      next unless cls = @classes[c]
+      m = @known_classes[m] || m
 
-        comment = RDoc::Comment.new '', @top_level
-        incl = cls.add_include RDoc::Include.new(m, comment)
-        incl.record_location @top_level
-      end
+      comment = RDoc::Comment.new '', @top_level
+      incl = cls.add_include RDoc::Include.new(m, comment)
+      incl.record_location @top_level
     end
   end
 
@@ -446,6 +457,10 @@ class RDoc::Parser::C < RDoc::Parser
     end
   end
 
+  ##
+  # Creates classes and module that were missing were defined due to the file
+  # order being different than the declaration order.
+
   def do_missing
     return if @missing_dependencies.empty?
 
@@ -797,7 +812,7 @@ class RDoc::Parser::C < RDoc::Parser
     parent_name = @known_classes[parent] || parent
 
     if in_module then
-      enclosure = @classes[in_module] || @store.c_enclosure_classes[in_module]
+      enclosure = @classes[in_module] || @store.find_c_enclosure(in_module)
 
       if enclosure.nil? and enclosure = @known_classes[in_module] then
         enc_type = /^rb_m/ =~ in_module ? :module : :class
@@ -844,8 +859,8 @@ class RDoc::Parser::C < RDoc::Parser
     end
 
     @classes[var_name] = cm
-    @store.c_enclosure_classes[var_name] = cm
     @known_classes[var_name] = cm.full_name
+    @store.add_c_enclosure var_name, cm
   end
 
   ##
@@ -1000,6 +1015,30 @@ class RDoc::Parser::C < RDoc::Parser
     end
   end
 
+  ##
+  # Loads the variable map with the given +name+ from the RDoc::Store, if
+  # present.
+
+  def load_variable_map map_name
+    return {} unless files = @store.cache[map_name]
+    return {} unless name_map = files[@file_name]
+
+    class_map = {}
+
+    name_map.each do |variable, name|
+      next unless mod = @store.find_class_or_module(name)
+
+      class_map[variable] = if map_name == :c_class_variables then
+                              mod
+                            else
+                              name
+                            end
+      @known_classes[variable] = name
+    end
+
+    class_map
+  end
+
   ##
   # Look for directives in a normal comment block:
   #
@@ -1132,6 +1171,9 @@ class RDoc::Parser::C < RDoc::Parser
     do_includes
     do_aliases
     do_attrs
+
+    @store.add_c_variables self
+
     @top_level
   end
 

data/lib/rdoc/parser/changelog.rb

@@ -0,0 +1,186 @@
+require 'time'
+
+##
+# A ChangeLog file parser.
+#
+# This parser converts a ChangeLog into an RDoc::Markup::Document.  When
+# viewed as HTML a ChangeLog page will have an entry for each day's entries in
+# the sidebar table of contents.
+#
+# This parser is meant to parse the MRI ChangeLog, but can be used to parse any
+# {GNU style Change
+# Log}[http://www.gnu.org/prep/standards/html_node/Style-of-Change-Logs.html].
+
+class RDoc::Parser::ChangeLog < RDoc::Parser
+
+  include RDoc::Parser::Text
+
+  parse_files_matching(/(\/|\\|\A)ChangeLog[^\/\\]*\z/)
+
+  ##
+  # Attaches the +continuation+ of the previous line to the +entry_body+.
+  #
+  # Continued function listings are joined together as a single entry.
+  # Continued descriptions are joined to make a single paragraph.
+
+  def continue_entry_body entry_body, continuation
+    return unless last = entry_body.last
+
+    if last =~ /\)\s*\z/ and continuation =~ /\A\(/ then
+      last.sub!(/\)\s*\z/, ',')
+      continuation.sub!(/\A\(/, '')
+    end
+
+    if last =~ /\s\z/ then
+      last << continuation
+    else
+      last << ' ' << continuation
+    end
+  end
+
+  ##
+  # Creates an RDoc::Markup::Document given the +groups+ of ChangeLog entries.
+
+  def create_document groups
+    doc = RDoc::Markup::Document.new
+    doc.omit_headings_below = 2
+    doc.file = @top_level
+
+    doc << RDoc::Markup::Heading.new(1, File.basename(@file_name))
+    doc << RDoc::Markup::BlankLine.new
+
+    groups.sort_by do |day,| day end.reverse_each do |day, entries|
+      doc << RDoc::Markup::Heading.new(2, day.dup)
+      doc << RDoc::Markup::BlankLine.new
+
+      doc.concat create_entries entries
+    end
+
+    doc
+  end
+
+  ##
+  # Returns a list of ChangeLog entries an RDoc::Markup nodes for the given
+  # +entries+.
+
+  def create_entries entries
+    out = []
+
+    entries.each do |entry, items|
+      out << RDoc::Markup::Heading.new(3, entry)
+      out << RDoc::Markup::BlankLine.new
+
+      out << create_items(items)
+    end
+
+    out
+  end
+
+  ##
+  # Returns an RDoc::Markup::List containing the given +items+ in the
+  # ChangeLog
+
+  def create_items items
+    list = RDoc::Markup::List.new :NOTE
+
+    items.each do |item|
+      item =~ /\A(.*?(?:\([^)]+\))?):\s*/
+
+      title = $1
+      body = $'
+
+      paragraph = RDoc::Markup::Paragraph.new body
+      list_item = RDoc::Markup::ListItem.new title, paragraph
+      list << list_item
+    end
+
+    list
+  end
+
+  ##
+  # Groups +entries+ by date.
+
+  def group_entries entries
+    entries.group_by do |title, _|
+      Time.parse(title).strftime "%Y-%m-%d"
+    end
+  end
+
+  ##
+  # Parses the entries in the ChangeLog.
+  #
+  # Returns an Array of each ChangeLog entry in order of parsing.
+  #
+  # A ChangeLog entry is an Array containing the ChangeLog title (date and
+  # committer) and an Array of ChangeLog items (file and function changed with
+  # description).
+  #
+  # An example result would be:
+  #
+  #    [ 'Tue Dec  4 08:33:46 2012  Eric Hodel  <drbrain@segment7.net>',
+  #      [ 'README.EXT:  Converted to RDoc format',
+  #        'README.EXT.ja:  ditto']]
+
+  def parse_entries
+    entries = []
+    entry_name = nil
+    entry_body = []
+
+    @content.each_line do |line|
+      case line
+      when /^\s*$/ then
+        next
+      when /^\w.*/ then
+        entries << [entry_name, entry_body] if entry_name
+
+        entry_name = $&
+
+        begin
+          time = Time.parse entry_name
+          # HACK Ruby 1.8 does not raise ArgumentError for Time.parse "Other"
+          entry_name = nil unless entry_name =~ /#{time.year}/
+        rescue ArgumentError
+          entry_name = nil
+        end
+
+        entry_body = []
+      when /^(\t| {8})?\*\s*(.*)/ then # "\t* file.c (func): ..."
+        entry_body << $2
+      when /^(\t| {8})?\s*(\(.*)/ then # "\t(func): ..."
+        entry = $2
+
+        if entry_body.last =~ /:/ then
+          entry_body << entry
+        else
+          continue_entry_body entry_body, entry
+        end
+      when /^(\t| {8})?\s*(.*)/ then
+        continue_entry_body entry_body, $2
+      end
+    end
+
+    entries << [entry_name, entry_body] if entry_name
+
+    entries.reject! do |(entry,_)|
+      entry == nil
+    end
+
+    entries
+  end
+
+  ##
+  # Converts the ChangeLog into an RDoc::Markup::Document
+
+  def scan
+    entries = parse_entries
+    grouped_entries = group_entries entries
+
+    doc = create_document grouped_entries
+
+    @top_level.comment = doc
+
+    @top_level
+  end
+
+end
+

data/lib/rdoc/parser/ruby.rb

@@ -240,7 +240,7 @@ class RDoc::Parser::Ruby < RDoc::Parser
   # with :: separated named) and return the ultimate name, the associated
   # container, and the given name (with the ::).
 
-  def get_class_or_module container
+  def get_class_or_module container, ignore_constants = false
     skip_tkspace
     name_t = get_tk
     given_name = ''
@@ -259,9 +259,16 @@ class RDoc::Parser::Ruby < RDoc::Parser
     while TkCOLON2 === peek_tk do
       prev_container = container
       container = container.find_module_named name_t.name
-      container ||= prev_container.add_module RDoc::NormalModule, name_t.name
+      container ||=
+        if ignore_constants then
+          RDoc::Context.new
+        else
+          c = prev_container.add_module RDoc::NormalModule, name_t.name
+          c.ignore unless prev_container.document_children
+          c
+        end
 
-      container.ignore unless prev_container.document_children
+      container.record_location @top_level
 
       get_tk
       skip_tkspace false
@@ -663,9 +670,10 @@ class RDoc::Parser::Ruby < RDoc::Parser
   end
 
   ##
-  # Parses a constant in +context+ with +comment+
+  # Parses a constant in +context+ with +comment+.  If +ignore_constants+ is
+  # true, no found constants will be added to RDoc.
 
-  def parse_constant container, tk, comment
+  def parse_constant container, tk, comment, ignore_constants = false
     offset  = tk.seek
     line_no = tk.line_no
 
@@ -676,6 +684,17 @@ class RDoc::Parser::Ruby < RDoc::Parser
 
     eq_tk = get_tk
 
+    if TkCOLON2 === eq_tk then
+      unget_tk eq_tk
+      unget_tk tk
+
+      container, name_t, = get_class_or_module container, ignore_constants
+
+      name = name_t.name
+
+      eq_tk = get_tk
+    end
+
     unless TkASSIGN === eq_tk then
       unget_tk eq_tk
       return false
@@ -1281,16 +1300,16 @@ class RDoc::Parser::Ruby < RDoc::Parser
   #
   # and add this as the block_params for the method
 
-  def parse_method_parameters(method)
+  def parse_method_parameters method
     res = parse_method_or_yield_parameters method
 
     res = "(#{res})" unless res =~ /\A\(/
     method.params = res unless method.params
 
-    if method.block_params.nil? then
-      skip_tkspace false
-      read_documentation_modifiers method, RDoc::METHOD_MODIFIERS
-    end
+    return if  method.block_params
+
+    skip_tkspace false
+    read_documentation_modifiers method, RDoc::METHOD_MODIFIERS
   end
 
   ##
@@ -1334,6 +1353,26 @@ class RDoc::Parser::Ruby < RDoc::Parser
     end
   end
 
+  ##
+  # Parses a rescue
+
+  def parse_rescue
+    skip_tkspace false
+
+    while tk = get_tk
+      case tk
+      when TkNL, TkSEMICOLON then
+        break
+      when TkCOMMA then
+        skip_tkspace false
+
+        get_tk if TkNL === peek_tk
+      end
+
+      skip_tkspace false
+    end
+  end
+
   ##
   # The core of the ruby parser.
 
@@ -1407,7 +1446,7 @@ class RDoc::Parser::Ruby < RDoc::Parser
         parse_method container, single, tk, comment
 
       when TkCONSTANT then
-        unless parse_constant container, tk, comment then
+        unless parse_constant container, tk, comment, current_method then
           try_parse_comment = true
         end
 
@@ -1441,6 +1480,9 @@ class RDoc::Parser::Ruby < RDoc::Parser
       when TkSUPER then
         current_method.calls_super = true if current_method
 
+      when TkRESCUE then
+        parse_rescue
+
       when TkIDENTIFIER then
         if nest == 1 and current_method.nil? then
           case tk.name

data/lib/rdoc/rdoc.rb

@@ -349,6 +349,12 @@ option)
     filename_path = Pathname(filename).expand_path
     relative_path = filename_path.relative_path_from @options.root
 
+    if @options.page_dir and
+       relative_path.to_s.start_with? @options.page_dir.to_s then
+      relative_path =
+        relative_path.relative_path_from @options.page_dir
+    end
+
     top_level = @store.add_file filename, relative_path.to_s
 
     parser = RDoc::Parser.for top_level, filename, content, @options, @stats
@@ -470,9 +476,12 @@ The internal error was:
     @store.dry_run  = @options.dry_run
     @store.main     = @options.main_page
     @store.title    = @options.title
+    @store.path     = @options.op_dir
 
     @start_time = Time.now
 
+    @store.load_cache
+
     file_info = parse_files @options.files
 
     @options.default_title = "RDoc Documentation"