rdoc 3.12.2 → 4.0.0.preview2

data/README.rdoc

@@ -3,28 +3,48 @@
 home :: https://github.com/rdoc/rdoc
 rdoc :: http://docs.seattlerb.org/rdoc
 bugs :: https://github.com/rdoc/rdoc/issues
+code quality :: {<img src="https://codeclimate.com/badge.png" />}[https://codeclimate.com/github/rdoc/rdoc]
 
 == Description
 
 RDoc produces HTML and command-line documentation for Ruby projects.  RDoc
-includes the +rdoc+ and +ri+ tools for generating and displaying online
-documentation.
+includes the +rdoc+ and +ri+ tools for generating and displaying documentation
+from the command-line.
 
-See RDoc for a description of RDoc's markup and basic use.
+== Generating Documentation
 
-== Synopsis
+Once installed, you can create documentation using the +rdoc+ command
 
-To learn RDoc's syntax and directives for documenting your ruby project see
-RDoc::Markup.  RDoc::Parser::Ruby and RDoc::Parser::C have additional
-directives (such as metaprogrammed methods) for documenting Ruby and C files
-respectively.
+  $ rdoc [options] [names...]
 
-To generate HTML documentation for your project run <tt>rdoc .</tt> in your
-project's root directory.
+For an up-to-date option summary, type
 
-To determine how well your project is documented run <tt>rdoc -C lib</tt> to
-get a documentation coverage report.  <tt>rdoc -C1 lib</tt> includes parameter
-names in the documentation coverage report.
+  $ rdoc --help
+
+A typical use might be to generate documentation for a package of Ruby
+source (such as RDoc itself).
+
+  $ rdoc
+
+This command generates documentation for all the Ruby and C source
+files in and below the current directory.  These will be stored in a
+documentation tree starting in the subdirectory +doc+.
+
+You can make this slightly more useful for your readers by having the
+index page contain the documentation for the primary file.  In our
+case, we could type
+
+  % rdoc --main README.rdoc
+
+You'll find information on the various formatting tricks you can use
+in comment blocks in the documentation this generates.
+
+RDoc uses file extensions to determine how to process each file.  File names
+ending +.rb+ and +.rbw+ are assumed to be Ruby source.  Files
+ending +.c+ are parsed as C files.  All other files are assumed to
+contain just Markup-style markup (with or without leading '#' comment
+markers).  If directory names are passed to RDoc, they are scanned
+recursively for C and Ruby source files only.
 
 To generate documentation using +rake+ see RDoc::Task.
 
@@ -40,22 +60,70 @@ To generate documentation programmatically:
   rdoc.document options
   # see RDoc::RDoc
 
+== Writing Documentation
+
+To write documentation for RDoc place a comment above the class, module,
+method, constant, or attribute you want documented:
+
+  ##
+  # This class represents an arbitrary shape by a series of points.
+
+  class Shape
+
+    ##
+    # Creates a new shape described by a +polyline+.
+    #
+    # If the +polyline+ does not end at the same point it started at the
+    # first pointed is copied and placed at the end of the line.
+    #
+    # An ArgumentError is raised if the line crosses itself, but shapes may
+    # be concave.
+
+    def initialize polyline
+      # ...
+    end
+
+  end
+
+The default comment markup format is the RDoc::Markup format.
+TomDoc[rdoc-ref:RDoc::TomDoc], Markdown[rdoc-ref:RDoc::Markdown] and
+RD[rdoc-ref:RDoc::RD] format comments are also supported.  You can set the
+default comment format for your entire project by creating a
+<tt>.rdoc_options</tt> file.  See RDoc::Options@Saved+Options for instructions
+on creating one.  You can also set the comment format for a single file
+through the +:markup:+ directive, but this is only recommended if you wish to
+switch markup formats.  See RDoc::Markup@Other+directives.
+
+Comments can contain directives that tell RDoc information that it cannot
+otherwise discover through parsing.  See RDoc::Markup@Directives to control
+what is or is not documented, to define method arguments or to break up
+methods in a class by topic.  See RDoc::Parser::Ruby for directives used to
+teach RDoc about metaprogrammed methods.
+
+See RDoc::Parser::C for documenting C extensions with RDoc.
+
+To determine how well your project is documented run <tt>rdoc -C lib</tt> to
+get a documentation coverage report.  <tt>rdoc -C1 lib</tt> includes parameter
+names in the documentation coverage report.
+
 == Bugs
 
-If you find a bug, please report it at the RDoc project's
-{issues tracker}[https://github.com/rdoc/rdoc/issues] on github.
+See DEVELOPERS@Bugs for information on filing a bug report.  It's OK to file a
+bug report for anything you're having a problem with.  If you can't figure out
+how to make RDoc produce the output you like that is probably a documentation
+bug.
 
 == License
 
 RDoc is Copyright (c) 2001-2003 Dave Thomas, The Pragmatic Programmers.
 Portions (c) 2007-2011 Eric Hodel.  Portions copyright others, see individual
-files for details.
+files and LEGAL.rdoc for details.
 
-It is free software, and may be redistributed under the terms specified in
-LICENSE.txt.
+RDoc is free software, and may be redistributed under the terms specified in
+LICENSE.rdoc.
 
 == Warranty
 
 This software is provided "as is" and without any express or implied
 warranties, including, without limitation, the implied warranties of
-merchantibility and fitness for a particular purpose.
+merchantability and fitness for a particular purpose.

data/Rakefile

@@ -10,11 +10,16 @@ task :test    => :generate
 PARSER_FILES = %w[
   lib/rdoc/rd/block_parser.rb
   lib/rdoc/rd/inline_parser.rb
+  lib/rdoc/markdown.rb
+  lib/rdoc/markdown/literals_1_8.rb
+  lib/rdoc/markdown/literals_1_9.rb
 ]
 
 Hoe.plugin :git
+Hoe.plugin :kpeg
 Hoe.plugin :minitest
 Hoe.plugin :rdoc_tags
+Hoe.plugin :travis
 
 $rdoc_rakefile = true
 
@@ -37,12 +42,12 @@ Depending on your version of ruby, you may need to install ruby rdoc/ri data:
 >= 1.9.2 : nothing to do! Yay!
   MESSAGE
 
+  self.licenses << 'Ruby'
   self.readme_file  = 'README.rdoc'
   self.history_file = 'History.rdoc'
   self.testlib = :minitest
   self.extra_rdoc_files += %w[
     DEVELOPERS.rdoc
-    CVE-2013-0256.rdoc
     History.rdoc
     LICENSE.rdoc
     LEGAL.rdoc
@@ -52,6 +57,7 @@ Depending on your version of ruby, you may need to install ruby rdoc/ri data:
   ]
 
   self.clean_globs += PARSER_FILES
+  self.kpeg_flags = '-fsv' if self.respond_to? :kpeg_flags= # no plugin
 
   require_ruby_version '>= 1.8.7'
   extra_deps     << ['json',     '~> 1.4']
@@ -64,6 +70,10 @@ Depending on your version of ruby, you may need to install ruby rdoc/ri data:
   spec_extras['homepage'] = 'http://docs.seattlerb.org/rdoc'
 end
 
+# requires ruby 1.8 and ruby 1.8 to build
+hoe.clean_globs -= PARSER_FILES.grep(/literals_/)
+
+task :generate => :isolate
 task :generate => PARSER_FILES
 task :check_manifest => :generate
 
@@ -134,4 +144,3 @@ task :diff_rubinius do
   sh "diff #{diff_options} test #{rubinius_dir}/test/rdoc; true"
 end
 
-

data/TODO.rdoc

@@ -1,12 +1,21 @@
 This file contains some things that might happen in RDoc, or might not.
 Forward Looking Statements applies.
 
-=== 3.next
+=== RDoc::VERSION.succ
+
+Blockers:
 
 * Update LICENSE to match ruby's switch
-* Reload the RDoc tree from an RI store
-  * Re-run generators
-  * Parse only changed files (like in ruby)
+* The alias keyword should not be bidirectional
+* Fix RDoc::Parser#use_markup to handle the filename (see TODO)
+* Restore backwards compatibility due to paragraph text joining from existing
+  ri files
+* Fix consumption of , after link like: RDoc[rdoc-ref:RDoc], <- comma here
+* Remove support for links like Matrix[*rows]
+
+Nice to have:
+
+* Parse only changed files (like in ruby)
 * Page of Glory (or Shame) in HTML output showing documentation coverage
   statistics.
 * Link to the parent-class implementation of methods that use super
@@ -15,26 +24,24 @@ Forward Looking Statements applies.
 * Method markup support for rd documentation (per rd syntax)
 * Improve SIGINFO handling
 * Global variable support
-* Page support for ri
 * Provide the code_object to directive handlers
-* Add markup parser documentation to DEVELOPERS.rdoc
 
 === 4
 
 API changes to RDoc
 
-* Remove global state
-* Remove RDoc::RDocError
 * RDoc::TopLevel#add_method should automatically create the appropriate method
   class rather than requiring one be passed in.
 * Remove #comment= from Context subclasses in favor of #add_comment
+* Add versions to RDoc::Markup syntax tree marshal format
+* Comments can no longer be Strings
+
+=== Crazy Ideas
+
+* Auto-normalize heading levels to look OK.  It's weird to see an <h1> in
+  the middle of a method section.
 * RDoc::CodeObject
   * Move into own namespace
   * Rename TopLevel to File
   * Rename Context to Container
   * Rename NormalClass to Class
-
-=== Crazy Ideas
-
-  * Auto-normalize heading levels to look OK.  It's weird to see an <h1> in
-    the middle of a method section.

data/bin/rdoc

@@ -18,6 +18,10 @@ require 'rdoc/rdoc'
 begin
   r = RDoc::RDoc.new
   r.document ARGV
+rescue Errno::ENOSPC
+  $stderr.puts 'Ran out of space creating documentation'
+  $stderr.puts
+  $stderr.puts 'Please free up some space and try again'
 rescue SystemExit
   raise
 rescue Exception => e

data/lib/gauntlet_rdoc.rb

@@ -36,7 +36,7 @@ class RDoc::Gauntlet < Gauntlet
 
     args = @args.dup
     args << '--op' << dir
-    args.push(*spec.rdoc_options)
+    args.concat spec.rdoc_options
     args << spec.require_paths
     args << spec.extra_rdoc_files
     args = args.flatten.map { |a| a.to_s }

data/lib/rdoc.rb

@@ -3,88 +3,53 @@ $DEBUG_RDOC = nil
 # :main: README.rdoc
 
 ##
-# RDoc is a Ruby documentation system which contains RDoc::RDoc for generating
-# documentation, RDoc::RI for interactive documentation and RDoc::Markup for
-# text markup.
+# RDoc produces documentation for Ruby source files by parsing the source and
+# extracting the definition for classes, modules, methods, includes and
+# requires.  It associates these with optional documentation contained in an
+# immediately preceding comment block then renders the result using an output
+# formatter.
 #
-# RDoc::RDoc produces documentation for Ruby source files.  It works similarly
-# to JavaDoc, parsing the source and extracting the definition for classes,
-# modules, methods, includes and requires.  It associates these with optional
-# documentation contained in an immediately preceding comment block then
-# renders the result using an output formatter.
-#
-# RDoc::Markup that converts plain text into various output formats.  The
-# markup library is used to interpret the comment blocks that RDoc uses to
-# document methods, classes, and so on.
-#
-# RDoc::RI implements the +ri+ command-line tool which displays on-line
-# documentation for ruby classes, methods, etc.  +ri+ features several output
-# formats and an interactive mode (<tt>ri -i</tt>).  See <tt>ri --help</tt>
-# for further details.
+# For a simple introduction to writing or generating documentation using RDoc
+# see the README.
 #
 # == Roadmap
 #
-# * If you think you found a bug in RDoc see DEVELOPERS@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.
-# * If you want to store rdoc configuration in your gem see
-#   RDoc::Options@Saved+Options
-# * If you want to write documentation for Ruby files see RDoc::Parser::Ruby
-# * If you want to write documentation for extensions written in C see
-#   RDoc::Parser::C
-# * If you want to generate documentation using <tt>rake</tt> see RDoc::Task.
-# * If you want to drive RDoc programmatically, see RDoc::RDoc.
-# * If you want to use the library to format text blocks into HTML or other
-#   formats, look at RDoc::Markup.
-# * If you want to make an RDoc plugin such as a generator or directive
-#   handler see RDoc::RDoc.
-# * If you want to write your own output generator see RDoc::Generator.
-# * If you want an overview of how RDoc works see DEVELOPERS
-#
-# == Summary
+# If you think you found a bug in RDoc see DEVELOPERS@Bugs
 #
-# Once installed, you can create documentation using the +rdoc+ command
+# 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.
 #
-#   % rdoc [options] [names...]
+# If you want to set the default markup format see
+# RDoc::Markup@Supported+Formats
 #
-# For an up-to-date option summary, type
+# If you want to store rdoc configuration in your gem (such as the default
+# markup format) see RDoc::Options@Saved+Options
 #
-#   % rdoc --help
+# If you want to write documentation for Ruby files see RDoc::Parser::Ruby
 #
-# A typical use might be to generate documentation for a package of Ruby
-# source (such as RDoc itself).
+# If you want to write documentation for extensions written in C see
+# RDoc::Parser::C
 #
-#   % rdoc
+# If you want to generate documentation using <tt>rake</tt> see RDoc::Task.
 #
-# This command generates documentation for all the Ruby and C source
-# files in and below the current directory.  These will be stored in a
-# documentation tree starting in the subdirectory +doc+.
+# If you want to drive RDoc programmatically, see RDoc::RDoc.
 #
-# You can make this slightly more useful for your readers by having the
-# index page contain the documentation for the primary file.  In our
-# case, we could type
+# If you want to use the library to format text blocks into HTML or other
+# formats, look at RDoc::Markup.
 #
-#   % rdoc --main README.rdoc
+# If you want to make an RDoc plugin such as a generator or directive handler
+# see RDoc::RDoc.
 #
-# You'll find information on the various formatting tricks you can use
-# in comment blocks in the documentation this generates.
+# If you want to write your own output generator see RDoc::Generator.
 #
-# RDoc uses file extensions to determine how to process each file.  File names
-# ending +.rb+ and +.rbw+ are assumed to be Ruby source.  Files
-# ending +.c+ are parsed as C files.  All other files are assumed to
-# contain just Markup-style markup (with or without leading '#' comment
-# markers).  If directory names are passed to RDoc, they are scanned
-# recursively for C and Ruby source files only.
+# If you want an overview of how RDoc works see DEVELOPERS
 #
-# == Other stuff
+# == Credits
 #
 # RDoc is currently being maintained by Eric Hodel <drbrain@segment7.net>.
 #
 # Dave Thomas <dave@pragmaticprogrammer.com> is the original author of RDoc.
 #
-# == Credits
-#
 # * The Ruby parser in rdoc/parse.rb is based heavily on the outstanding
 #   work of Keiju ISHITSUKA of Nippon Rational Inc, who produced the Ruby
 #   parser for irb and the rtags package.
@@ -96,19 +61,10 @@ module RDoc
 
   class Error < RuntimeError; end
 
-  def self.const_missing const_name # :nodoc:
-    if const_name.to_s == 'RDocError' then
-      warn "RDoc::RDocError is deprecated and will be removed in RDoc 4"
-      return Error
-    end
-
-    super
-  end
-
   ##
   # RDoc version you are using
 
-  VERSION = '3.12.2'
+  VERSION = '4.0.0.preview2'
 
   ##
   # Method visibilities
@@ -170,15 +126,19 @@ module RDoc
 
   autoload :CrossReference, 'rdoc/cross_reference'
   autoload :ERBIO,          'rdoc/erbio'
+  autoload :ERBPartial,     'rdoc/erb_partial'
   autoload :Encoding,       'rdoc/encoding'
   autoload :Generator,      'rdoc/generator'
   autoload :Options,        'rdoc/options'
   autoload :Parser,         'rdoc/parser'
+  autoload :Servlet,        'rdoc/servlet'
   autoload :RI,             'rdoc/ri'
   autoload :Stats,          'rdoc/stats'
+  autoload :Store,          'rdoc/store'
   autoload :Task,           'rdoc/task'
   autoload :Text,           'rdoc/text'
 
+  autoload :Markdown,       'rdoc/markdown'
   autoload :Markup,         'rdoc/markup'
   autoload :RD,             'rdoc/rd'
   autoload :TomDoc,         'rdoc/tom_doc'
@@ -215,6 +175,7 @@ module RDoc
 
   autoload :Constant,       'rdoc/constant'
   autoload :Include,        'rdoc/include'
+  autoload :Extend,         'rdoc/extend'
   autoload :Require,        'rdoc/require'
 
 end

data/lib/rdoc/any_method.rb

@@ -3,7 +3,14 @@
 
 class RDoc::AnyMethod < RDoc::MethodAttr
 
-  MARSHAL_VERSION = 1 # :nodoc:
+  ##
+  # 2::
+  #   RDoc 4
+  #   Added calls_super
+  #   Added parent name and class
+  #   Added section title
+
+  MARSHAL_VERSION = 2 # :nodoc:
 
   ##
   # Don't rename \#initialize to \::new
@@ -25,6 +32,11 @@ class RDoc::AnyMethod < RDoc::MethodAttr
 
   attr_accessor :params
 
+  ##
+  # If true this method uses +super+ to call a superclass version
+
+  attr_accessor :calls_super
+
   include RDoc::TokenStream
 
   ##
@@ -36,6 +48,8 @@ class RDoc::AnyMethod < RDoc::MethodAttr
     @c_function = nil
     @dont_rename_initialize = false
     @token_stream = nil
+    @calls_super = false
+    @superclass_method = nil
   end
 
   ##
@@ -93,7 +107,11 @@ class RDoc::AnyMethod < RDoc::MethodAttr
       @block_params,
       aliases,
       @params,
-      @file.absolute_name,
+      @file.relative_name,
+      @calls_super,
+      @parent.name,
+      @parent.class,
+      @section.title,
     ]
   end
 
@@ -104,34 +122,44 @@ class RDoc::AnyMethod < RDoc::MethodAttr
   # * #full_name
   # * #parent_name
 
-  def marshal_load(array)
+  def marshal_load array
     @dont_rename_initialize = nil
     @is_alias_for           = nil
     @token_stream           = nil
     @aliases                = []
-
-    version       = array[0]
-    @name         = array[1]
-    @full_name    = array[2]
-    @singleton    = array[3]
-    @visibility   = array[4]
-    @comment      = array[5]
-    @call_seq     = array[6]
-    @block_params = array[7]
+    @parent                 = nil
+    @parent_name            = nil
+    @parent_class           = nil
+    @section                = nil
+    @file                   = nil
+
+    version        = array[0]
+    @name          = array[1]
+    @full_name     = array[2]
+    @singleton     = array[3]
+    @visibility    = array[4]
+    @comment       = array[5]
+    @call_seq      = array[6]
+    @block_params  = array[7]
+    #                      8 handled below
+    @params        = array[9]
+    #                      10 handled below
+    @calls_super   = array[11]
+    @parent_name   = array[12]
+    @parent_title  = array[13]
+    @section_title = array[14]
 
     array[8].each do |new_name, comment|
       add_alias RDoc::Alias.new(nil, @name, new_name, comment, @singleton)
     end
 
-    @params       = array[9]
-
-    @parent_name = if @full_name =~ /#/ then
-                     $`
-                   else
-                     name = @full_name.split('::')
-                     name.pop
-                     name.join '::'
-                   end
+    @parent_name ||= if @full_name =~ /#/ then
+                       $`
+                     else
+                       name = @full_name.split('::')
+                       name.pop
+                       name.join '::'
+                     end
 
     @file = RDoc::TopLevel.new array[10] if version > 0
   end
@@ -204,5 +232,31 @@ class RDoc::AnyMethod < RDoc::MethodAttr
     params
   end
 
+  ##
+  # Sets the store for this method and its referenced code objects.
+
+  def store= store
+    super
+
+    @file = @store.add_file @file.full_name if @file
+  end
+
+  ##
+  # For methods that +super+, find the superclass method that would be called.
+
+  def superclass_method
+    return unless @calls_super
+    return @superclass_method if @superclass_method
+
+    parent.each_ancestor do |ancestor|
+      if method = ancestor.method_list.find { |m| m.name == @name } then
+        @superclass_method = method
+        break
+      end
+    end
+
+    @superclass_method
+  end
+
 end