rdoc 6.3.3 → 6.5.0

data/lib/rdoc/method_attr.rb

@@ -289,7 +289,7 @@ class RDoc::MethodAttr < RDoc::CodeObject
   # HTML id-friendly method/attribute name
 
   def html_name
-    require 'cgi'
+    require 'cgi/util'
 
     CGI.escape(@name.gsub('-', '-2D')).gsub('%','-').sub(/^-/, '')
   end

data/lib/rdoc/normal_class.rb

@@ -56,7 +56,7 @@ class RDoc::NormalClass < RDoc::ClassModule
   def pretty_print q # :nodoc:
     superclass = @superclass ? " < #{@superclass}" : nil
 
-    q.group 2, "[class #{full_name}#{superclass} ", "]" do
+    q.group 2, "[class #{full_name}#{superclass}", "]" do
       q.breakable
       q.text "includes:"
       q.breakable

data/lib/rdoc/normal_module.rb

@@ -30,7 +30,7 @@ class RDoc::NormalModule < RDoc::ClassModule
   end
 
   def pretty_print q # :nodoc:
-    q.group 2, "[module #{full_name}: ", "]" do
+    q.group 2, "[module #{full_name}:", "]" do
       q.breakable
       q.text "includes:"
       q.breakable

data/lib/rdoc/options.rb

@@ -106,6 +106,7 @@ class RDoc::Options
     generator_options
     generators
     op_dir
+    page_dir
     option_parser
     pipe
     rdoc_include
@@ -338,6 +339,10 @@ class RDoc::Options
 
   attr_reader :visibility
 
+  ##
+  # Indicates if files of test suites should be skipped
+  attr_accessor :skip_tests
+
   def initialize loaded_options = nil # :nodoc:
     init_ivars
     override loaded_options if loaded_options
@@ -385,6 +390,7 @@ class RDoc::Options
     @write_options = false
     @encoding = Encoding::UTF_8
     @charset = @encoding.name
+    @skip_tests = true
   end
 
   def init_with map # :nodoc:
@@ -434,6 +440,7 @@ class RDoc::Options
     @main_page      = map['main_page']      if map.has_key?('main_page')
     @markup         = map['markup']         if map.has_key?('markup')
     @op_dir         = map['op_dir']         if map.has_key?('op_dir')
+    @page_dir       = map['page_dir']       if map.has_key?('page_dir')
     @show_hash      = map['show_hash']      if map.has_key?('show_hash')
     @tab_width      = map['tab_width']      if map.has_key?('tab_width')
     @template_dir   = map['template_dir']   if map.has_key?('template_dir')
@@ -513,19 +520,22 @@ class RDoc::Options
   ##
   # For dumping YAML
 
-  def encode_with coder # :nodoc:
+  def to_yaml(*options) # :nodoc:
     encoding = @encoding ? @encoding.name : nil
 
-    coder.add 'encoding', encoding
-    coder.add 'static_path',  sanitize_path(@static_path)
-    coder.add 'rdoc_include', sanitize_path(@rdoc_include)
+    yaml = {}
+    yaml['encoding'] = encoding
+    yaml['static_path'] = sanitize_path(@static_path)
+    yaml['rdoc_include'] = sanitize_path(@rdoc_include)
+    yaml['page_dir'] = (sanitize_path([@page_dir]).first if @page_dir)
 
     ivars = instance_variables.map { |ivar| ivar.to_s[1..-1] }
     ivars -= SPECIAL
 
     ivars.sort.each do |ivar|
-      coder.add ivar, instance_variable_get("@#{ivar}")
+      yaml[ivar] = instance_variable_get("@#{ivar}")
     end
+    yaml.to_yaml
   end
 
   ##
@@ -548,6 +558,11 @@ class RDoc::Options
   # #template.
 
   def finish
+    if @write_options then
+      write_options
+      exit
+    end
+
     @op_dir ||= 'doc'
 
     @rdoc_include << "." if @rdoc_include.empty?
@@ -585,14 +600,14 @@ class RDoc::Options
   def finish_page_dir
     return unless @page_dir
 
-    @files << @page_dir.to_s
+    @files << @page_dir
 
-    page_dir = nil
+    page_dir = Pathname(@page_dir)
     begin
-      page_dir = @page_dir.expand_path.relative_path_from @root
+      page_dir = page_dir.expand_path.relative_path_from @root
     rescue ArgumentError
       # On Windows, sometimes crosses different drive letters.
-      page_dir = @page_dir.expand_path
+      page_dir = page_dir.expand_path
     end
 
     @page_dir = page_dir
@@ -768,6 +783,13 @@ Usage: #{opt.program_name} [options] [names...]
 
       opt.separator nil
 
+      opt.on("--no-skipping-tests", nil,
+             "Don't skip generating documentation for test and spec files") do |value|
+        @skip_tests = false
+      end
+
+      opt.separator nil
+
       opt.on("--extension=NEW=OLD", "-E",
              "Treat files ending with .new as if they",
              "ended with .old. Using '-E cgi=rb' will",
@@ -847,7 +869,7 @@ Usage: #{opt.program_name} [options] [names...]
              "such files at your project root.",
              "NOTE: Do not use the same file name in",
              "the page dir and the root of your project") do |page_dir|
-        @page_dir = Pathname(page_dir)
+        @page_dir = page_dir
       end
 
       opt.separator nil
@@ -971,7 +993,7 @@ Usage: #{opt.program_name} [options] [names...]
       opt.on("--template-stylesheets=FILES", PathArray,
              "Set (or add to) the list of files to",
              "include with the html template.") do |value|
-        @template_stylesheets << value
+        @template_stylesheets.concat value
       end
 
       opt.separator nil
@@ -1159,13 +1181,6 @@ Usage: #{opt.program_name} [options] [names...]
 
     @files = argv.dup
 
-    finish
-
-    if @write_options then
-      write_options
-      exit
-    end
-
     self
   end
 
@@ -1278,8 +1293,37 @@ Usage: #{opt.program_name} [options] [names...]
     File.open '.rdoc_options', 'w' do |io|
       io.set_encoding Encoding::UTF_8
 
-      YAML.dump self, io
+      io.print to_yaml
     end
   end
 
+  ##
+  # Loads options from .rdoc_options if the file exists, otherwise creates a
+  # new RDoc::Options instance.
+
+  def self.load_options
+    options_file = File.expand_path '.rdoc_options'
+    return RDoc::Options.new unless File.exist? options_file
+
+    RDoc.load_yaml
+
+    begin
+      options = YAML.safe_load File.read('.rdoc_options'), permitted_classes: [RDoc::Options, Symbol]
+    rescue Psych::SyntaxError
+      raise RDoc::Error, "#{options_file} is not a valid rdoc options file"
+    end
+
+    return RDoc::Options.new unless options # Allow empty file.
+
+    raise RDoc::Error, "#{options_file} is not a valid rdoc options file" unless
+      RDoc::Options === options or Hash === options
+
+    if Hash === options
+      # Override the default values with the contents of YAML file.
+      options = RDoc::Options.new options
+    end
+
+    options
+  end
+
 end

data/lib/rdoc/parser/c.rb

@@ -122,6 +122,11 @@ class RDoc::Parser::C < RDoc::Parser
 
   include RDoc::Text
 
+  # :stopdoc:
+  BOOL_ARG_PATTERN = /\s*+\b([01]|Q?(?:true|false)|TRUE|FALSE)\b\s*/
+  TRUE_VALUES = ['1', 'TRUE', 'true', 'Qtrue'].freeze
+  # :startdoc:
+
   ##
   # Maps C variable names to names of Ruby classes or modules
 
@@ -173,6 +178,8 @@ class RDoc::Parser::C < RDoc::Parser
     @classes           = load_variable_map :c_class_variables
     @singleton_classes = load_variable_map :c_singleton_class_variables
 
+    @markup = @options.markup
+
     # class_variable => { function => [method, ...] }
     @methods = Hash.new { |h, f| h[f] = Hash.new { |i, m| i[m] = [] } }
 
@@ -257,18 +264,18 @@ class RDoc::Parser::C < RDoc::Parser
     @content.scan(/rb_attr\s*\(
                    \s*(\w+),
                    \s*([\w"()]+),
-                   \s*([01]),
-                   \s*([01]),
-                   \s*\w+\);/xm) do |var_name, attr_name, read, write|
+                   #{BOOL_ARG_PATTERN},
+                   #{BOOL_ARG_PATTERN},
+                   \s*\w+\);/xmo) do |var_name, attr_name, read, write|
       handle_attr var_name, attr_name, read, write
     end
 
     @content.scan(%r%rb_define_attr\(
                              \s*([\w\.]+),
                              \s*"([^"]+)",
-                             \s*(\d+),
-                             \s*(\d+)\s*\);
-                %xm) do |var_name, attr_name, read, write|
+                             #{BOOL_ARG_PATTERN},
+                             #{BOOL_ARG_PATTERN}\);
+                %xmo) do |var_name, attr_name, read, write|
       handle_attr var_name, attr_name, read, write
     end
   end
@@ -293,94 +300,92 @@ class RDoc::Parser::C < RDoc::Parser
 
     @content.scan(
       %r(
+        (?<open>\s*\(\s*) {0}
+        (?<close>\s*\)\s*) {0}
+        (?<name>\s*"(?<class_name>\w+)") {0}
+        (?<parent>\s*(?:
+          (?<parent_name>[\w\*\s\(\)\.\->]+) |
+          rb_path2class\s*\(\s*"(?<path>[\w:]+)"\s*\)
+        )) {0}
+        (?<under>\w+) {0}
+
         (?<var_name>[\w\.]+)\s* =
         \s*rb_(?:
           define_(?:
-            class(?: # rb_define_class(class_name_1, parent_name_1)
-              \s*\(
-                \s*"(?<class_name_1>\w+)",
-                \s*(?<parent_name_1>\w+)\s*
-              \)
-            |
-              _under\s*\( # rb_define_class_under(class_under, class_name2, parent_name2...)
-                \s* (?<class_under>\w+),
-                \s* "(?<class_name_2>\w+)",
-                \s*
-                (?:
-                  (?<parent_name_2>[\w\*\s\(\)\.\->]+) |
-                  rb_path2class\("(?<path>[\w:]+)"\)
-                )
+            class(?: # rb_define_class(name, parent_name)
+              \(\s*
+                \g<name>,
+                \g<parent>
               \s*\)
+            |
+              _under\g<open> # rb_define_class_under(under, name, parent_name...)
+                \g<under>,
+                \g<name>,
+                \g<parent>
+              \g<close>
             )
           |
-            module(?: # rb_define_module(module_name_1)
-              \s*\(
-                \s*"(?<module_name_1>\w+)"\s*
-              \)
+            (?<module>)
+            module(?: # rb_define_module(name)
+              \g<open>
+                \g<name>
+              \g<close>
             |
-              _under\s*\( # rb_define_module_under(module_under, module_name_2)
-                \s*(?<module_under>\w+),
-                \s*"(?<module_name_2>\w+)"
-              \s*\)
+              _under\g<open> # rb_define_module_under(under, name)
+                \g<under>,
+                \g<name>
+              \g<close>
             )
           )
       |
-        struct_define_without_accessor\s*\( # rb_struct_define_without_accessor(class_name_3, parent_name_3, ...)
-          \s*"(?<class_name_3>\w+)",
-          \s*(?<parent_name_3>\w+),
-          \s*\w+,        # Allocation function
-          (?:\s*"\w+",)* # Attributes
-          \s*NULL
-        \)
+        (?<attributes>(?:\s*"\w+",)*\s*NULL\s*) {0}
+        struct_define(?:
+          \g<open> # rb_struct_define(name, ...)
+            \g<name>,
+        |
+          _under\g<open> # rb_struct_define_under(under, name, ...)
+            \g<under>,
+            \g<name>,
+        |
+          _without_accessor(?:
+            \g<open> # rb_struct_define_without_accessor(name, parent_name, ...)
+          |
+            _under\g<open> # rb_struct_define_without_accessor_under(under, name, parent_name, ...)
+              \g<under>,
+          )
+            \g<name>,
+            \g<parent>,
+            \s*\w+,        # Allocation function
+        )
+          \g<attributes>
+        \g<close>
       |
-        singleton_class\s*\( # rb_singleton_class(target_class_name)
-          \s*(?<target_class_name>\w+)
-        \)
+        singleton_class\g<open> # rb_singleton_class(target_class_name)
+          (?<target_class_name>\w+)
+        \g<close>
         )
       )mx
     ) do
-      class_name = $~[:class_name_1]
-      type = :class
-      if class_name
-        # rb_define_class(class_name_1, parent_name_1)
-        parent_name = $~[:parent_name_1]
-        #under = nil
-      else
-        class_name = $~[:class_name_2]
-        if class_name
-          # rb_define_class_under(class_under, class_name2, parent_name2...)
-          parent_name = $~[:parent_name_2] || $~[:path]
-          under = $~[:class_under]
-        else
-          class_name = $~[:class_name_3]
-          if class_name
-            # rb_struct_define_without_accessor(class_name_3, parent_name_3, ...)
-            parent_name = $~[:parent_name_3]
-            #under = nil
-          else
-            type = :module
-            class_name = $~[:module_name_1]
-            #parent_name = nil
-            if class_name
-              # rb_define_module(module_name_1)
-              #under = nil
-            else
-              class_name = $~[:module_name_2]
-              if class_name
-                # rb_define_module_under(module_under, module_name_1)
-                under = $~[:module_under]
-              else
-                # rb_singleton_class(target_class_name)
-                target_class_name = $~[:target_class_name]
-                handle_singleton $~[:var_name], target_class_name
-                next
-              end
-            end
-          end
-        end
+      if target_class_name = $~[:target_class_name]
+        # rb_singleton_class(target_class_name)
+        handle_singleton $~[:var_name], target_class_name
+        next
       end
 
-      handle_class_module($~[:var_name], type, class_name, parent_name, under)
+      var_name = $~[:var_name]
+      type = $~[:module] ? :module : :class
+      class_name = $~[:class_name]
+      parent_name = $~[:parent_name] || $~[:path]
+      under = $~[:under]
+      attributes = $~[:attributes]
+
+      handle_class_module(var_name, type, class_name, parent_name, under)
+      if attributes and !parent_name # rb_struct_define *not* without_accessor
+        true_flag = 'Qtrue'
+        attributes.scan(/"\K\w+(?=")/) do |attr_name|
+          handle_attr var_name, attr_name, true_flag, true_flag
+        end
+      end
     end
   end
 
@@ -439,7 +444,7 @@ class RDoc::Parser::C < RDoc::Parser
       next unless cls = @classes[c]
       m = @known_classes[m] || m
 
-      comment = RDoc::Comment.new '', @top_level, :c
+      comment = new_comment '', @top_level, :c
       incl = cls.add_include RDoc::Include.new(m, comment)
       incl.record_location @top_level
     end
@@ -521,7 +526,7 @@ class RDoc::Parser::C < RDoc::Parser
                                    \s*"#{Regexp.escape new_name}"\s*,
                                    \s*"#{Regexp.escape old_name}"\s*\);%xm
 
-    RDoc::Comment.new($1 || '', @top_level, :c)
+    new_comment($1 || '', @top_level, :c)
   end
 
   ##
@@ -560,7 +565,7 @@ class RDoc::Parser::C < RDoc::Parser
                 ''
               end
 
-    RDoc::Comment.new comment, @top_level, :c
+    new_comment comment, @top_level, :c
   end
 
   ##
@@ -600,7 +605,7 @@ class RDoc::Parser::C < RDoc::Parser
 
     case type
     when :func_def
-      comment = RDoc::Comment.new args[0], @top_level, :c
+      comment = new_comment args[0], @top_level, :c
       body = args[1]
       offset, = args[2]
 
@@ -630,7 +635,7 @@ class RDoc::Parser::C < RDoc::Parser
 
       body
     when :macro_def
-      comment = RDoc::Comment.new args[0], @top_level, :c
+      comment = new_comment args[0], @top_level, :c
       body = args[1]
       offset, = args[2]
 
@@ -675,13 +680,14 @@ class RDoc::Parser::C < RDoc::Parser
   ##
   # Finds a RDoc::NormalClass or RDoc::NormalModule for +raw_name+
 
-  def find_class(raw_name, name)
+  def find_class(raw_name, name, base_name = nil)
     unless @classes[raw_name]
       if raw_name =~ /^rb_m/
         container = @top_level.add_module RDoc::NormalModule, name
       else
         container = @top_level.add_class RDoc::NormalClass, name
       end
+      container.name = base_name if base_name
 
       container.record_location @top_level
       @classes[raw_name] = container
@@ -722,7 +728,7 @@ class RDoc::Parser::C < RDoc::Parser
         ((?>/\*.*?\*/\s+))
         (static\s+)?
         void\s+
-        Init_#{class_name}\s*(?:_\(\s*)?\(\s*(?:void\s*)?\)%xmi then
+        Init(?:VM)?_(?i:#{class_name})\s*(?:_\(\s*)?\(\s*(?:void\s*)?\)%xm then
       comment = $1.sub(%r%Document-(?:class|module):\s+#{class_name}%, '')
     elsif @content =~ %r%Document-(?:class|module):\s+#{class_name}\s*?
                          (?:<\s+[:,\w]+)?\n((?>.*?\*/))%xm then
@@ -737,7 +743,7 @@ class RDoc::Parser::C < RDoc::Parser
       comment = ''
     end
 
-    comment = RDoc::Comment.new comment, @top_level, :c
+    comment = new_comment comment, @top_level, :c
     comment.normalize
 
     look_for_directives_in class_mod, comment
@@ -782,7 +788,7 @@ class RDoc::Parser::C < RDoc::Parser
       table[const_name] ||
       ''
 
-    RDoc::Comment.new comment, @top_level, :c
+    new_comment comment, @top_level, :c
   end
 
   ##
@@ -813,7 +819,7 @@ class RDoc::Parser::C < RDoc::Parser
 
     return unless comment
 
-    RDoc::Comment.new comment, @top_level, :c
+    new_comment comment, @top_level, :c
   end
 
   ##
@@ -822,8 +828,8 @@ class RDoc::Parser::C < RDoc::Parser
 
   def handle_attr(var_name, attr_name, read, write)
     rw = ''
-    rw += 'R' if '1' == read
-    rw += 'W' if '1' == write
+    rw += 'R' if TRUE_VALUES.include?(read)
+    rw += 'W' if TRUE_VALUES.include?(write)
 
     class_name = @known_classes[var_name]
 
@@ -919,7 +925,7 @@ class RDoc::Parser::C < RDoc::Parser
 
     return unless class_name
 
-    class_obj = find_class var_name, class_name
+    class_obj = find_class var_name, class_name, class_name[/::\K[^:]+\z/]
 
     unless class_obj then
       @options.warn 'Enclosing class or module %p is not known' % [const_name]
@@ -947,7 +953,7 @@ class RDoc::Parser::C < RDoc::Parser
 
         new_comment = "#{$1}#{new_comment.lstrip}"
 
-        new_comment = RDoc::Comment.new new_comment, @top_level, :c
+        new_comment = self.new_comment(new_comment, @top_level, :c)
 
         con = RDoc::Constant.new const_name, new_definition, new_comment
       else
@@ -1023,12 +1029,18 @@ class RDoc::Parser::C < RDoc::Parser
                           elsif p_count == -1 then # argc, argv
                             rb_scan_args body
                           else
-                            "(#{(1..p_count).map { |i| "p#{i}" }.join ', '})"
+                            args = (1..p_count).map { |i| "p#{i}" }
+                            "(#{args.join ', '})"
                           end
 
 
         meth_obj.record_location @top_level
+
+        if meth_obj.section_title
+          class_obj.temporary_section = class_obj.add_section(meth_obj.section_title)
+        end
         class_obj.add_method meth_obj
+
         @stats.add_method meth_obj
         meth_obj.visibility = :private if 'private_method' == type
       end
@@ -1045,23 +1057,6 @@ class RDoc::Parser::C < RDoc::Parser
     @singleton_classes[sclass_var] = class_name
   end
 
-  ##
-  # Normalizes tabs in +body+
-
-  def handle_tab_width(body)
-    if /\t/ =~ body
-      tab_width = @options.tab_width
-      body.split(/\n/).map do |line|
-        1 while line.gsub!(/\t+/) do
-          ' ' * (tab_width * $&.length - $`.length % tab_width)
-        end && $~
-        line
-      end.join "\n"
-    else
-      body
-    end
-  end
-
   ##
   # Loads the variable map with the given +name+ from the RDoc::Store, if
   # present.
@@ -1222,4 +1217,9 @@ class RDoc::Parser::C < RDoc::Parser
     @top_level
   end
 
+  def new_comment text = nil, location = nil, language = nil
+    RDoc::Comment.new(text, location, language).tap do |comment|
+      comment.format = @markup
+    end
+  end
 end

data/lib/rdoc/parser/ruby.rb

@@ -164,15 +164,7 @@ class RDoc::Parser::Ruby < RDoc::Parser
   def initialize(top_level, file_name, content, options, stats)
     super
 
-    if /\t/ =~ content then
-      tab_width = @options.tab_width
-      content = content.split(/\n/).map do |line|
-        1 while line.gsub!(/\t+/) {
-          ' ' * (tab_width*$&.length - $`.length % tab_width)
-        }  && $~
-        line
-      end.join("\n")
-    end
+    content = handle_tab_width(content)
 
     @size = 0
     @token_listeners = nil
@@ -399,6 +391,29 @@ class RDoc::Parser::Ruby < RDoc::Parser
     return [container, name_t, given_name, new_modules]
   end
 
+  ##
+  # Skip opening parentheses and yield the block.
+  # Skip closing parentheses too when exists.
+
+  def skip_parentheses(&block)
+    left_tk = peek_tk
+
+    if :on_lparen == left_tk[:kind]
+      get_tk
+
+      ret = skip_parentheses(&block)
+
+      right_tk = peek_tk
+      if :on_rparen == right_tk[:kind]
+        get_tk
+      end
+
+      ret
+    else
+      yield
+    end
+  end
+
   ##
   # Return a superclass, which can be either a constant of an expression
 
@@ -833,7 +848,7 @@ class RDoc::Parser::Ruby < RDoc::Parser
       cls = parse_class_regular container, declaration_context, single,
         name_t, given_name, comment
     elsif name_t[:kind] == :on_op && name_t[:text] == '<<'
-      case name = get_class_specification
+      case name = skip_parentheses { get_class_specification }
       when 'self', container.name
         read_documentation_modifiers cls, RDoc::CLASS_MODIFIERS
         parse_statements container, SINGLE
@@ -1193,6 +1208,22 @@ class RDoc::Parser::Ruby < RDoc::Parser
     end
   end
 
+  ##
+  # Parses an +included+ with a block feature of ActiveSupport::Concern.
+
+  def parse_included_with_activesupport_concern container, comment # :nodoc:
+    skip_tkspace_without_nl
+    tk = get_tk
+    unless tk[:kind] == :on_lbracket || (tk[:kind] == :on_kw && tk[:text] == 'do')
+      unget_tk tk
+      return nil # should be a block
+    end
+
+    parse_statements container
+
+    container
+  end
+
   ##
   # Parses identifiers that can create new methods or change visibility.
   #
@@ -1893,6 +1924,8 @@ class RDoc::Parser::Ruby < RDoc::Parser
           parse_extend_or_include RDoc::Include, container, comment
         when "extend" then
           parse_extend_or_include RDoc::Extend, container, comment
+        when "included" then
+          parse_included_with_activesupport_concern container, comment
         end
 
       else