rdoc 3.1 → 6.3.3

data/LEGAL.rdoc

@@ -0,0 +1,50 @@
+# coding: UTF-8
+
+= Legal Notice Information
+
+The files in this distribution are covered by the Ruby license (see LICENSE) except the features mentioned below:
+
+Darkfish::
+  Darkfish was written by Michael Granger and is included under the MIT
+  license.  Darkfish contains images from the Silk Icons set by Mark James.
+
+  See lib/rdoc/generator/darkfish.rb for license information.
+
+  * lib/rdoc/generator/darkfish.rb
+  * lib/rdoc/generator/template/darkfish/*
+  * lib/rdoc/generator/template/darkfish/images
+
+SDoc::
+  Portions of SDoc by (Володя Колесников) Vladimir Kolesnikov are included
+  under the MIT license as RDoc::Generator::JsonIndex.  See
+  lib/rdoc/generator/json_index.rb for license information.
+
+  * lib/rdoc/generator/json_index.rb
+  * lib/rdoc/generator/template/json_index/*
+  * The +#search_index+ methods on RDoc::CodeObject subclasses were derived
+    from sdoc.
+  * RDoc::ClassModule#document_self_or_methods comes from SDoc.
+
+peg-markdown::
+  RDoc's Markdown support is derived from peg-markdown by John MacFarlane.  It
+  is used under the MIT license.  See RDoc::Markdown for license details.
+
+MarkdownTest::
+  test/test_rdoc_markdown_test.rb uses MarkdownTest 1.0.3's source files which
+  are included as test/MarkdownTest_1.0.3/*.text which are Copyright (c)
+  2004-2005 John Gruber http://daringfireball.net and is included under the
+  same terms as Perl itself.
+
+  See http://dev.perl.org/licenses/ for the terms of the Perl license.
+
+Fonts::
+  Source Code Pro is (c) 2010, 2012 Adobe Systems Incorporated.
+
+  Lato is (c) 2010 Łukasz Dziedzic.
+
+  Both fonts are used under the SIL Open Font License, Version 1.1.  The
+  license is available at http://scripts.sil.org/OFL
+
+  See lib/rdoc/generator/template/darkfish/fonts.css for complete copyright
+  and license information, including a copy of the OFL.
+

data/LICENSE.rdoc

@@ -0,0 +1,57 @@
+RDoc is copyrighted free software.
+
+You can redistribute it and/or modify it under either the terms of the GPL
+version 2 (see the file GPL), or the conditions below:
+
+1. You may make and give away verbatim copies of the source form of the
+   software without restriction, provided that you duplicate all of the
+   original copyright notices and associated disclaimers.
+
+2. You may modify your copy of the software in any way, provided that
+   you do at least ONE of the following:
+
+   a. place your modifications in the Public Domain or otherwise
+      make them Freely Available, such as by posting said
+      modifications to Usenet or an equivalent medium, or by allowing
+      the author to include your modifications in the software.
+
+   b. use the modified software only within your corporation or
+      organization.
+
+   c. give non-standard binaries non-standard names, with
+      instructions on where to get the original software distribution.
+
+   d. make other distribution arrangements with the author.
+
+3. You may distribute the software in object code or binary form,
+   provided that you do at least ONE of the following:
+
+   a. distribute the binaries and library files of the software,
+      together with instructions (in the manual page or equivalent)
+      on where to get the original distribution.
+
+   b. accompany the distribution with the machine-readable source of
+      the software.
+
+   c. give non-standard binaries non-standard names, with
+      instructions on where to get the original software distribution.
+
+   d. make other distribution arrangements with the author.
+
+4. You may modify and include the part of the software into any other
+   software (possibly commercial).  But some files in the distribution
+   are not written by the author, so that they are not under these terms.
+
+   For the list of those files and their copying conditions, see the
+   file LEGAL.
+
+5. The scripts and library files supplied as input to or produced as
+   output from the software do not automatically fall under the
+   copyright of the software, but belong to whomever generated them,
+   and may be sold commercially, and may be aggregated with this
+   software.
+
+6. THIS SOFTWARE IS PROVIDED "AS IS" AND WITHOUT ANY EXPRESS OR
+   IMPLIED WARRANTIES, INCLUDING, WITHOUT LIMITATION, THE IMPLIED
+   WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
+   PURPOSE.

data/README.rdoc

@@ -0,0 +1,129 @@
+= \RDoc - Ruby Documentation System
+
+home :: https://github.com/ruby/rdoc
+rdoc :: https://ruby.github.io/rdoc
+bugs :: https://github.com/ruby/rdoc/issues
+code quality :: {<img src="https://codeclimate.com/github/ruby/rdoc/badges/gpa.svg" alt="Code Climate">}[https://codeclimate.com/github/ruby/rdoc]
+
+== Description
+
+RDoc produces HTML and command-line documentation for Ruby projects.  RDoc
+includes the +rdoc+ and +ri+ tools for generating and displaying documentation
+from the command-line.
+
+== Generating Documentation
+
+Once installed, you can create documentation using the +rdoc+ command
+
+  $ rdoc [options] [names...]
+
+For an up-to-date option summary, type
+
+  $ 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[https://ruby.github.io/rdoc/RDocTask.html].
+
+To generate documentation programmatically:
+
+  gem 'rdoc'
+  require 'rdoc/rdoc'
+
+  options = RDoc::Options.new
+  # see RDoc::Options
+
+  rdoc = RDoc::RDoc.new
+  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
+
+See CONTRIBUTING@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 and LEGAL.rdoc for details.
+
+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
+merchantability and fitness for a particular purpose.

data/RI.rdoc

@@ -0,0 +1,57 @@
+= RI
+
++ri+ is a tool that allows Ruby documentation to be viewed on the command-line.
+
+You can use +ri+ to look up information from either the command line or
+interactively.  When you run +ri+ without any arguments it will launch in
+interactive mode.  In interactive mode you can tab-complete class and method
+names.
+
+== Usage
+
+To see information for a class, do:
+  ri ClassName
+
+For example, for the Array class, do:
+  ri Array
+
+To see information on a method on a class, do:
+  ri ClassName.method
+
+This will show both instance and class methods.  For example, the IO
+class defines both IO::read and IO#read:
+  ri IO.read
+
+To see information for an instance method, do:
+  ri ClassName#method_name
+
+For example, for Array's +join+ method, do:
+  ri Array#join
+
+To see information for a class method, do:
+  ri ClassName::method_name
+
+For example, for Module's +private+ method, do:
+  ri Module::private
+
+To read documentation for all +read+ methods, do:
+  ri read
+
+== Options
+
++ri+ supports a variety of options, all of which can be viewed via +--help+.
+Of particular interest, are:
+
+[<tt>-f</tt>]
+  Outputs ri data using the selected formatter.  You can see the available
+  formatters in <tt>ri --help</tt>
+[<tt>-T</tt>]
+  Send output to stdout, rather than to a pager.
+
+All options also can be specified through the +RI+ environment variable.
+Command-line options always override those specified in the +RI+ environment
+variable.
+
+The +RI_PAGER+ environment variable allows you to choose a particular pager or
+particular options for your pager.
+

data/Rakefile

@@ -1,98 +1,101 @@
-require 'hoe'
-$:.unshift 'lib'
-require 'rdoc/rdoc'
+$:.unshift File.expand_path 'lib'
+require 'rdoc/task'
+require 'bundler/gem_tasks'
+require 'rake/testtask'
 
-Hoe.plugin :git
-Hoe.plugin :isolate
-Hoe.plugin :minitest
+task :docs    => :generate
+task :test    => [:normal_test, :rubygems_test]
 
-$rdoc_rakefile = true
-
-Hoe.spec 'rdoc' do
-  developer 'Eric Hodel', 'drbrain@segment7.net'
-  developer 'Dave Thomas', ''
-  developer 'Phil Hagelberg', 'technomancy@gmail.com'
-  developer 'Tony Strauss', 'tony.strauss@designingpatterns.com'
-
-  self.remote_rdoc_dir = ''
-  self.rsync_args = '-avz'
-  self.testlib = :minitest
-  self.isolate_dir = 'tmp/isolated'
-
-  extra_dev_deps   << ['minitest', '~> 2']
-  extra_dev_deps   << ['isolate',  '~> 3']
-  extra_rdoc_files << 'Rakefile'
-  spec_extras['required_rubygems_version'] = '>= 1.3'
-  spec_extras['homepage'] = 'http://rdoc.rubyforge.org'
-
-  spec_extras[:post_install_message] = <<-EOF
-RDoc 2.5 did not save method parameters, so you should upgrade your rdoc-data
-gem to a version >= 2.5.3.
-
-To have ri data for core and stdlib you'll need to:
-
-  gem install rdoc-data
+PARSER_FILES = %w[
+  lib/rdoc/rd/block_parser.ry
+  lib/rdoc/rd/inline_parser.ry
+  lib/rdoc/markdown.kpeg
+  lib/rdoc/markdown/literals.kpeg
+]
 
-then run:
+$rdoc_rakefile = true
 
-  rdoc-data --install
+task :default => :test
 
-To have ri data for you gems you'll also need to run:
+RDoc::Task.new do |doc|
+  doc.main = 'README.rdoc'
+  doc.title = "rdoc #{RDoc::VERSION} Documentation"
+  doc.rdoc_dir = 'html'
+  doc.rdoc_files = FileList.new %w[lib/**/*.rb *.rdoc] - PARSER_FILES
+end
 
-  gem rdoc --all --overwrite
+task ghpages: :rdoc do
+  `git checkout gh-pages`
+  require "fileutils"
+  FileUtils.rm_rf "/tmp/html"
+  FileUtils.mv "html", "/tmp"
+  FileUtils.rm_rf "*"
+  FileUtils.cp_r Dir.glob("/tmp/html/*"), "."
+end
 
-If you don't want to rebuild the rdoc for `gem server`, add --no-rdoc.
-  EOF
+Rake::TestTask.new(:normal_test) do |t|
+  t.libs << "test/rdoc"
+  t.verbose = true
+  t.deps = :generate
+  t.test_files = FileList["test/**/test_*.rb"].exclude("test/rdoc/test_rdoc_rubygems_hook.rb")
 end
 
-# These tasks expect to have the following directory structure:
-#
-#   git/git.rubini.us/code # Rubinius git HEAD checkout
-#   svn/ruby/trunk         # ruby subversion HEAD checkout
-#   svn/rdoc/trunk         # RDoc subversion HEAD checkout
-#
-# If you don't have this directory structure, set RUBY_PATH and/or
-# RUBINIUS_PATH.
-
-diff_options = "-urpN --exclude '*svn*' --exclude '*swp' --exclude '*rbc'"
-rsync_options = "-avP --exclude '*svn*' --exclude '*swp' --exclude '*rbc' --exclude '*.rej' --exclude '*.orig'"
-
-rubinius_dir = ENV['RUBINIUS_PATH'] || '../../../git/git.rubini.us/code'
-ruby_dir = ENV['RUBY_PATH'] || '../../ruby/trunk'
-
-desc "Updates Ruby HEAD with the currently checked-out copy of RDoc."
-task :update_ruby do
-  sh "rsync #{rsync_options} bin/rdoc #{ruby_dir}/bin/rdoc"
-  sh "rsync #{rsync_options} bin/ri #{ruby_dir}/bin/ri"
-  sh "rsync #{rsync_options} lib/ #{ruby_dir}/lib"
-  sh "rsync #{rsync_options} test/ #{ruby_dir}/test/rdoc"
+Rake::TestTask.new(:rubygems_test) do |t|
+  t.libs << "test/rdoc"
+  t.verbose = true
+  t.deps = :generate
+  t.pattern = "test/rdoc/test_rdoc_rubygems_hook.rb"
 end
 
-desc "Diffs Ruby HEAD with the currently checked-out copy of RDoc."
-task :diff_ruby do
-  options = "-urpN --exclude '*svn*' --exclude '*swp' --exclude '*rbc'"
+path = "pkg/#{Bundler::GemHelper.gemspec.full_name}"
 
-  sh "diff #{diff_options} bin/rdoc #{ruby_dir}/bin/rdoc; true"
-  sh "diff #{diff_options} bin/ri #{ruby_dir}/bin/ri; true"
-  sh "diff #{diff_options} lib/rdoc.rb #{ruby_dir}/lib/rdoc.rb; true"
-  sh "diff #{diff_options} lib/rdoc #{ruby_dir}/lib/rdoc; true"
-  sh "diff #{diff_options} test #{ruby_dir}/test/rdoc; true"
-end
+package_parser_files = PARSER_FILES.map do |parser_file|
+  name = File.basename(parser_file, File.extname(parser_file))
+  _path = File.dirname(parser_file)
+  package_parser_file = "#{path}/#{name}.rb"
+  parsed_file = "#{_path}/#{name}.rb"
+
+  file package_parser_file => parsed_file # ensure copy runs before racc
 
-desc "Updates Rubinius HEAD with the currently checked-out copy of RDoc."
-task :update_rubinius do
-  sh "rsync #{rsync_options} bin/rdoc #{rubinius_dir}/lib/bin/rdoc.rb"
-  sh "rsync #{rsync_options} bin/ri #{rubinius_dir}/lib/bin/ri.rb"
-  sh "rsync #{rsync_options} lib/ #{rubinius_dir}/lib"
-  sh "rsync #{rsync_options} test/ #{rubinius_dir}/test/rdoc"
+  package_parser_file
 end
 
-desc "Diffs Rubinius HEAD with the currently checked-out copy of RDoc."
-task :diff_rubinius do
-  sh "diff #{diff_options} bin/rdoc #{rubinius_dir}/lib/bin/rdoc.rb; true"
-  sh "diff #{diff_options} bin/ri #{rubinius_dir}/lib/bin/ri.rb; true"
-  sh "diff #{diff_options} lib/rdoc.rb #{rubinius_dir}/lib/rdoc.rb; true"
-  sh "diff #{diff_options} lib/rdoc #{rubinius_dir}/lib/rdoc; true"
-  sh "diff #{diff_options} test #{rubinius_dir}/test/rdoc; true"
+parsed_files = PARSER_FILES.map do |parser_file|
+  ext = File.extname(parser_file)
+  parsed_file = "#{parser_file.chomp(ext)}.rb"
+
+  file parsed_file => parser_file do |t|
+    puts "Generating #{parsed_file}..."
+    case ext
+    when '.ry' # need racc
+      racc = Gem.bin_path 'racc', 'racc'
+      rb_file = parser_file.gsub(/\.ry\z/, ".rb")
+      ruby "#{racc} -l -o #{rb_file} #{parser_file}"
+      open(rb_file, 'r+') do |f|
+        newtext = "# frozen_string_literal: true\n#{f.read}"
+        f.rewind
+        f.write newtext
+      end
+    when '.kpeg' # need kpeg
+      kpeg = Gem.bin_path 'kpeg', 'kpeg'
+      rb_file = parser_file.gsub(/\.kpeg\z/, ".rb")
+      ruby "#{kpeg} -fsv -o #{rb_file} #{parser_file}"
+    end
+  end
+
+  parsed_file
 end
 
+task "#{path}.gem" => package_parser_files
+desc "Generate all files used racc and kpeg"
+task :generate => parsed_files
+
+begin
+  require 'rubocop/rake_task'
+rescue LoadError
+else
+  RuboCop::RakeTask.new(:rubocop) do |t|
+    t.options = [*parsed_files]
+  end
+  task :build => [:generate, "rubocop:auto_correct"]
+end

data/TODO.rdoc

@@ -0,0 +1,59 @@
+This file contains some things that might happen in RDoc, or might not.
+Forward Looking Statements applies.
+
+=== RDoc::VERSION.succ
+
+Blockers:
+
+* Update LICENSE to match ruby's switch
+* 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
+* Add direct accessor to RDoc::Options to RDoc::Task
+* Remove "Public" in HTML output if there are only public methods
+* Method markup support for rd documentation (per rd syntax)
+* Improve SIGINFO handling
+* Global variable support
+* Provide the code_object to directive handlers
+
+=== 4
+
+API changes to RDoc
+
+* 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
+
+=== Accessibility
+
+Page title in right hand side
+
+Table of contents in left hand side as sub-list under main heading
+
+For class list, never method list, method summary at top
+
+table-of-contents-navigation div => nav + role="navigation"
+
+type "mod", focus is still on "mod"

data/bin/console

@@ -0,0 +1,7 @@
+#!/usr/bin/env ruby
+
+require "bundler/setup"
+require "rdoc"
+
+require "irb"
+IRB.start

data/bin/setup

@@ -0,0 +1,6 @@
+#!/usr/bin/env bash
+set -euo pipefail
+IFS=$'\n\t'
+set -vx
+
+bundle install

data/{bin → exe}/rdoc

@@ -5,14 +5,23 @@
 #
 #  Copyright (c) 2003 Dave Thomas
 #  Released under the same terms as Ruby
-#
-#  $Revision: 15033 $
+
+begin
+  gem 'rdoc'
+rescue NameError => e # --disable-gems
+  raise unless e.name == :gem
+rescue Gem::LoadError
+end
 
 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/exe/ri

@@ -0,0 +1,12 @@
+#!/usr/bin/env ruby
+
+begin
+  gem 'rdoc'
+rescue NameError => e # --disable-gems
+  raise unless e.name == :gem
+rescue Gem::LoadError
+end
+
+require 'rdoc/ri/driver'
+
+RDoc::RI::Driver.run ARGV

data/lib/rdoc/alias.rb

@@ -1,5 +1,4 @@
-require 'rdoc/code_object'
-
+# frozen_string_literal: true
 ##
 # Represent an alias, which is an old_name/new_name pair associated with a
 # particular context

data/lib/rdoc/anon_class.rb

@@ -1,9 +1,10 @@
-require 'rdoc/class_module'
-
+# frozen_string_literal: true
 ##
 # An anonymous class like:
 #
 #   c = Class.new do end
+#
+# AnonClass is currently not used.
 
 class RDoc::AnonClass < RDoc::ClassModule
 end