rdoc 3.1 → 6.3.3

data/lib/rdoc.rb

@@ -1,77 +1,56 @@
+# frozen_string_literal: true
 $DEBUG_RDOC = nil
 
-# :main: README.txt
+# :main: README.rdoc
 
 ##
-# = \RDoc - Ruby Documentation System
-#
-# This package contains RDoc and RDoc::Markup.  RDoc is an application that
-# produces documentation for one or more Ruby source files.  It works similarly
-# to JavaDoc, parsing the source, and extracting the definition for classes,
-# modules, and methods (along with includes and requires).  It associates with
-# these optional documentation contained in the immediately preceding comment
-# block, and then renders the result using a pluggable output formatter.
-# RDoc::Markup is a library 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 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.
 #
-# == Roadmap
+# For a simple introduction to writing or generating documentation using RDoc
+# see the README.
 #
-# * If you want to use RDoc to create documentation for your Ruby source files,
-#   read the summary below, and refer to <tt>rdoc --help</tt> for command line
-#   usage, and RDoc::Markup for a detailed description of RDoc's markup.
-# * If you want to generate documentation for extensions written in C, see
-#   RDoc::Parser::C
-# * If you want to drive RDoc programmatically, see RDoc::RDoc.
-# * If you want to use the library to format text blocks into HTML, 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 try writing your own output generator see RDoc::Generator.
+# == Roadmap
 #
-# == Summary
+# If you think you found a bug in RDoc see CONTRIBUTING@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.txt
+# 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 CONTRIBUTING
 #
-# == 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.
@@ -83,19 +62,7 @@ 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"
-      return Error
-    end
-
-    super
-  end
-
-  ##
-  # RDoc version you are using
-
-  VERSION = '3.1'
+  require 'rdoc/version'
 
   ##
   # Method visibilities
@@ -134,5 +101,101 @@ module RDoc
   METHOD_MODIFIERS = GENERAL_MODIFIERS +
     %w[arg args yield yields notnew not-new not_new doc]
 
-end
+  ##
+  # Loads the best available YAML library.
+
+  def self.load_yaml
+    begin
+      gem 'psych'
+    rescue NameError => e # --disable-gems
+      raise unless e.name == :gem
+    rescue Gem::LoadError
+    end
+
+    begin
+      require 'psych'
+    rescue ::LoadError
+    ensure
+      require 'yaml'
+    end
+  end
 
+  def self.home
+    rdoc_dir = begin
+                File.expand_path('~/.rdoc')
+              rescue ArgumentError
+              end
+
+    if File.directory?(rdoc_dir)
+      rdoc_dir
+    else
+      begin
+        # XDG
+        xdg_data_home = ENV["XDG_DATA_HOME"] || File.join(File.expand_path("~"), '.local', 'share')
+        unless File.exist?(xdg_data_home)
+          FileUtils.mkdir_p xdg_data_home
+        end
+        File.join xdg_data_home, "rdoc"
+      rescue Errno::EACCES
+      end
+    end
+  end
+
+  autoload :RDoc,           'rdoc/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'
+
+  autoload :KNOWN_CLASSES,  'rdoc/known_classes'
+
+  autoload :TokenStream,    'rdoc/token_stream'
+
+  autoload :Comment,        'rdoc/comment'
+
+  require 'rdoc/i18n'
+
+  # code objects
+  #
+  # We represent the various high-level code constructs that appear in Ruby
+  # programs: classes, modules, methods, and so on.
+  autoload :CodeObject,     'rdoc/code_object'
+
+  autoload :Context,        'rdoc/context'
+  autoload :TopLevel,       'rdoc/top_level'
+
+  autoload :AnonClass,      'rdoc/anon_class'
+  autoload :ClassModule,    'rdoc/class_module'
+  autoload :NormalClass,    'rdoc/normal_class'
+  autoload :NormalModule,   'rdoc/normal_module'
+  autoload :SingleClass,    'rdoc/single_class'
+
+  autoload :Alias,          'rdoc/alias'
+  autoload :AnyMethod,      'rdoc/any_method'
+  autoload :MethodAttr,     'rdoc/method_attr'
+  autoload :GhostMethod,    'rdoc/ghost_method'
+  autoload :MetaMethod,     'rdoc/meta_method'
+  autoload :Attr,           'rdoc/attr'
+
+  autoload :Constant,       'rdoc/constant'
+  autoload :Mixin,          'rdoc/mixin'
+  autoload :Include,        'rdoc/include'
+  autoload :Extend,         'rdoc/extend'
+  autoload :Require,        'rdoc/require'
+
+end

data/man/ri.1

@@ -0,0 +1,247 @@
+.\"Ruby is copyrighted by Yukihiro Matsumoto <matz@netlab.jp>.
+.Dd April 20, 2017
+.Dt RI \&1 "Ruby Programmer's Reference Guide"
+.Os UNIX
+.Sh NAME
+.Nm ri
+.Nd Ruby API reference front end
+.Sh SYNOPSIS
+.Nm
+.Op Fl ahilTv
+.Op Fl d Ar DIRNAME
+.Op Fl f Ar FORMAT
+.Op Fl w Ar WIDTH
+.Op Fl - Ns Oo Cm no- Oc Ns Cm pager
+.Op Fl -server Ns Oo = Ns Ar PORT Oc
+.Op Fl - Ns Oo Cm no- Oc Ns Cm list-doc-dirs
+.Op Fl -no-standard-docs
+.Op Fl - Ns Oo Cm no- Oc Ns Bro Cm system Ns | Ns Cm site Ns | Ns Cm gems Ns | Ns Cm home Brc
+.Op Fl - Ns Oo Cm no- Oc Ns Cm profile
+.Op Fl -dump Ns = Ns Ar CACHE
+.Op Ar name ...
+.Sh DESCRIPTION
+.Nm
+is a command-line front end for the Ruby API reference.
+You can search and read the API reference for classes and methods with
+.Nm .
+.Pp
+.Nm
+is a part of Ruby.
+.Pp
+.Ar name
+can be:
+.Bl -diag -offset indent
+.It Class | Module | Module::Class
+.Pp
+.It Class::method | Class#method | Class.method | method
+.Pp
+.It gem_name: | gem_name:README | gem_name:History
+.El
+.Pp
+All class names may be abbreviated to their minimum unambiguous form.
+If a name is ambiguous, all valid options will be listed.
+.Pp
+A
+.Ql \&.
+matches either class or instance methods, while #method
+matches only instance and ::method matches only class methods.
+.Pp
+README and other files may be displayed by prefixing them with the gem name
+they're contained in.  If the gem name is followed by a
+.Ql \&:
+all files in the gem will be shown.
+The file name extension may be omitted where it is unambiguous.
+.Pp
+For example:
+.Bd -literal -offset indent
+ri Fil
+ri File
+ri File.new
+ri zip
+ri rdoc:README
+.Ed
+.Pp
+Note that shell quoting or escaping may be required for method names
+containing punctuation:
+.Bd -literal -offset indent
+ri 'Array.[]'
+ri compact\e!
+.Ed
+.Pp
+To see the default directories
+.Nm
+will search, run:
+.Bd -literal -offset indent
+ri --list-doc-dirs
+.Ed
+.Pp
+Specifying the
+.Fl -system , Fl -site , Fl -home , Fl -gems ,
+or
+.Fl -doc-dir
+options will limit
+.Nm
+to searching only the specified directories.
+.Pp
+.Nm
+options may be set in the
+.Ev RI
+environment variable.
+.Pp
+The
+.Nm
+pager can be set with the
+.Ev RI_PAGER
+environment variable or the
+.Ev PAGER
+environment variable.
+.Pp
+.Sh OPTIONS
+.Bl -tag -width "1234567890123" -compact
+.Pp
+.It Fl i
+.It Fl - Ns Oo Cm no- Oc Ns Cm interactive
+In interactive mode you can repeatedly
+look up methods with autocomplete.
+.Pp
+.It Fl a
+.It Fl - Ns Oo Cm no- Oc Ns Cm all
+Show all documentation for a class or module.
+.Pp
+.It Fl l
+.It Fl - Ns Oo Cm no- Oc Ns Cm list
+List classes
+.Nm
+knows about.
+.Pp
+.It Fl - Ns Oo Cm no- Oc Ns Cm pager
+Send output to a pager,
+rather than directly to stdout.
+.Pp
+.It Fl T
+Synonym for
+.Fl -no-pager .
+.Pp
+.It Fl w Ar WIDTH
+.It Fl -width Ns = Ns Ar WIDTH
+Set the width of the output.
+.Pp
+.It Fl -server Ns Oo = Ns Ar PORT Oc
+Run RDoc server on the given port.
+The default port is\~8214.
+.Pp
+.It Fl f Ar FORMAT
+.It Fl -format Ns = Ns Ar FORMAT
+Use the selected formatter.
+The default formatter is
+.Li bs
+for paged output and
+.Li ansi
+otherwise.
+Valid formatters are:
+.Li ansi , Li bs , Li markdown , Li rdoc .
+.Pp
+.It Fl h
+.It Fl -help
+Show help and exit.
+.Pp
+.It Fl v
+.It Fl -version
+Output version information and exit.
+.El
+.Pp
+Data source options:
+.Bl -tag -width "1234567890123" -compact
+.Pp
+.It Fl - Ns Oo Cm no- Oc Ns Cm list-doc-dirs
+List the directories from which
+.Nm
+will source documentation on stdout and exit.
+.Pp
+.It Fl d Ar DIRNAME
+.It Fl -doc-dir Ns = Ns Ar DIRNAME
+List of directories from which to source
+documentation in addition to the standard
+directories.  May be repeated.
+.Pp
+.It Fl -no-standard-docs
+Do not include documentation from the Ruby standard library,
+.Pa site_lib ,
+installed gems, or
+.Pa ~/.rdoc .
+Use with
+.Fl -doc-dir .
+.Pp
+.It Fl - Ns Oo Cm no- Oc Ns Cm system
+Include documentation from Ruby's standard library.  Defaults to true.
+.Pp
+.It Fl - Ns Oo Cm no- Oc Ns Cm site
+Include documentation from libraries installed in
+.Pa site_lib .
+Defaults to true.
+.Pp
+.It Fl - Ns Oo Cm no- Oc Ns Cm gems
+Include documentation from RubyGems.  Defaults to true.
+.Pp
+.It Fl - Ns Oo Cm no- Oc Ns Cm home
+Include documentation stored in
+.Pa ~/.rdoc .
+Defaults to true.
+.El
+.Pp
+Debug options:
+.Bl -tag -width "1234567890123" -compact
+.Pp
+.It Fl - Ns Oo Cm no- Oc Ns Cm profile
+Run with the Ruby profiler.
+.Pp
+.It Fl -dump Ns = Ns Ar CACHE
+Dump data from an ri cache or data file.
+.El
+.Pp
+.Sh ENVIRONMENT
+.Bl -tag -width "USERPROFILE" -compact
+.Pp
+.It Ev RI
+Options to prepend to those specified on the command-line.
+.Pp
+.It Ev RI_PAGER
+.It Ev PAGER
+Pager program to use for displaying.
+.Pp
+.It Ev HOME
+.It Ev USERPROFILE
+.It Ev HOMEPATH
+Path to the user's home directory.
+.El
+.Pp
+.Sh FILES
+.Bl -tag -width "USERPROFILE" -compact
+.Pp
+.It Pa ~/.rdoc
+Path for ri data in the user's home directory.
+.Pp
+.El
+.Pp
+.Sh SEE ALSO
+.Xr ruby 1 ,
+.Xr rdoc 1 ,
+.Xr gem 1
+.Pp
+.Sh REPORTING BUGS
+.Bl -bullet
+.It
+Security vulnerabilities should be reported via an email to
+.Mt security@ruby-lang.org .
+Reported problems will be published after being fixed.
+.Pp
+.It
+Other bugs and feature requests can be reported via the
+Ruby Issue Tracking System
+.Pq Lk https://bugs.ruby-lang.org/ .
+Do not report security vulnerabilities
+via this system because it publishes the vulnerabilities immediately.
+.El
+.Sh AUTHORS
+Written by
+.An Dave Thomas Aq dave@pragmaticprogrammer.com .