rdoc 3.1 → 6.3.3

data/lib/rdoc/task.rb

@@ -1,3 +1,4 @@
+# frozen_string_literal: true
 #--
 # Copyright (c) 2003, 2004 Jim Weirich, 2009 Eric Hodel
 #
@@ -21,25 +22,23 @@
 # WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
 #++
 
-require 'rubygems'
 begin
   gem 'rdoc'
 rescue Gem::LoadError
-end
+end unless defined?(RDoc)
 
 begin
   gem 'rake'
 rescue Gem::LoadError
-end
+end unless defined?(Rake)
 
 require 'rdoc'
 require 'rake'
 require 'rake/tasklib'
 
 ##
-# Create a documentation task that will generate the RDoc files for a project.
-#
-# The RDoc::Task will create the following targets:
+# RDoc::Task creates the following rake tasks to generate and clean up RDoc
+# output:
 #
 # [rdoc]
 #   Main task for this RDoc task.
@@ -53,15 +52,14 @@ require 'rake/tasklib'
 #
 # Simple Example:
 #
-#   gem 'rdoc'
 #   require 'rdoc/task'
 #
-#   RDoc::Task.new do |rd|
-#     rd.main = "README.rdoc"
-#     rd.rdoc_files.include("README.rdoc", "lib/**/*.rb")
+#   RDoc::Task.new do |rdoc|
+#     rdoc.main = "README.rdoc"
+#     rdoc.rdoc_files.include("README.rdoc", "lib/**/*.rb")
 #   end
 #
-# The +rd+ object passed to the block is an RDoc::Task object. See the
+# The +rdoc+ object passed to the block is an RDoc::Task object. See the
 # attributes list for the RDoc::Task class for available customization options.
 #
 # == Specifying different task names
@@ -70,13 +68,12 @@ require 'rake/tasklib'
 # generating two sets of documentation.  For instance, if you want to have a
 # development set of documentation including private methods:
 #
-#   gem 'rdoc'
 #   require 'rdoc/task'
 #
-#   RDoc::Task.new :rdoc_dev do |rd|
-#     rd.main = "README.doc"
-#     rd.rdoc_files.include("README.rdoc", "lib/**/*.rb")
-#     rd.options << "--all"
+#   RDoc::Task.new :rdoc_dev do |rdoc|
+#     rdoc.main = "README.doc"
+#     rdoc.rdoc_files.include("README.rdoc", "lib/**/*.rb")
+#     rdoc.options << "--all"
 #   end
 #
 # The tasks would then be named :<em>rdoc_dev</em>,
@@ -88,7 +85,6 @@ require 'rake/tasklib'
 #
 # For example:
 #
-#   gem 'rdoc'
 #   require 'rdoc/task'
 #
 #   RDoc::Task.new(:rdoc => "rdoc", :clobber_rdoc => "rdoc:clean",
@@ -104,6 +100,12 @@ class RDoc::Task < Rake::TaskLib
 
   attr_accessor :name
 
+  ##
+  # Comment markup format.  rdoc, rd and tomdoc are supported.  (default is
+  # 'rdoc')
+
+  attr_accessor :markup
+
   ##
   # Name of directory to receive the html output files. (default is "html")
 
@@ -126,7 +128,8 @@ class RDoc::Task < Rake::TaskLib
   attr_accessor :template
 
   ##
-  # Name of format generator (--fmt) used by rdoc. (defaults to rdoc's default)
+  # Name of format generator (<tt>--format</tt>) used by rdoc. (defaults to
+  # rdoc's default)
 
   attr_accessor :generator
 
@@ -149,17 +152,45 @@ class RDoc::Task < Rake::TaskLib
   # Create an RDoc task with the given name. See the RDoc::Task class overview
   # for documentation.
 
-  def initialize(name = :rdoc)  # :yield: self
-    if name.is_a? Hash then
-      invalid_options = name.keys.map { |k| k.to_sym } -
-        [:rdoc, :clobber_rdoc, :rerdoc]
+  def initialize name = :rdoc # :yield: self
+    defaults
 
-      unless invalid_options.empty? then
-        raise ArgumentError, "invalid options: #{invalid_options.join(", ")}"
-      end
-    end
+    check_names name
 
     @name = name
+
+    yield self if block_given?
+
+    define
+  end
+
+  ##
+  # Ensures that +names+ only includes names for the :rdoc, :clobber_rdoc and
+  # :rerdoc.  If other names are given an ArgumentError is raised.
+
+  def check_names names
+    return unless Hash === names
+
+    invalid_options =
+      names.keys.map { |k| k.to_sym } - [:rdoc, :clobber_rdoc, :rerdoc]
+
+    unless invalid_options.empty? then
+      raise ArgumentError, "invalid options: #{invalid_options.join ', '}"
+    end
+  end
+
+  ##
+  # Task description for the clobber rdoc task or its renamed equivalent
+
+  def clobber_task_description
+    "Remove RDoc HTML files"
+  end
+
+  ##
+  # Sets default task values
+
+  def defaults
+    @name = :rdoc
     @rdoc_files = Rake::FileList.new
     @rdoc_dir = 'html'
     @main = nil
@@ -167,14 +198,12 @@ class RDoc::Task < Rake::TaskLib
     @template = nil
     @generator = nil
     @options = []
-    yield self if block_given?
-    define
   end
 
   ##
   # All source is inline now.  This method is deprecated
 
-  def inline_source() # :nodoc:
+  def inline_source # :nodoc:
     warn "RDoc::Task#inline_source is deprecated"
     true
   end
@@ -190,13 +219,13 @@ class RDoc::Task < Rake::TaskLib
   # Create the tasks defined by this task lib.
 
   def define
-    desc "Build RDoc HTML files"
+    desc rdoc_task_description
     task rdoc_task_name
 
-    desc "Rebuild RDoc HTML files"
+    desc rerdoc_task_description
     task rerdoc_task_name => [clobber_task_name, rdoc_task_name]
 
-    desc "Remove RDoc HTML files"
+    desc clobber_task_description
     task clobber_task_name do
       rm_r @rdoc_dir rescue nil
     end
@@ -215,11 +244,8 @@ class RDoc::Task < Rake::TaskLib
       @before_running_rdoc.call if @before_running_rdoc
       args = option_list + @rdoc_files
 
-      if Rake.application.options.trace then
-        $stderr.puts "rdoc #{args.join ' '}"
-      end
-      require 'rdoc/rdoc'
-      RDoc::RDoc.new.document(args)
+      $stderr.puts "rdoc #{args.join ' '}" if Rake.application.options.trace
+      RDoc::RDoc.new.document args
     end
 
     self
@@ -230,11 +256,12 @@ class RDoc::Task < Rake::TaskLib
 
   def option_list
     result = @options.dup
-    result << "-o"      << @rdoc_dir
-    result << "--main"  << main      if main
-    result << "--title" << title     if title
-    result << "-T"      << template  if template
-    result << '-f'      << generator if generator
+    result << "-o"       << @rdoc_dir
+    result << "--main"   << main      if main
+    result << "--markup" << markup    if markup
+    result << "--title"  << title     if title
+    result << "-T"       << template  if template
+    result << '-f'       << generator if generator
     result
   end
 
@@ -247,10 +274,24 @@ class RDoc::Task < Rake::TaskLib
     @before_running_rdoc = block
   end
 
+  ##
+  # Task description for the rdoc task or its renamed equivalent
+
+  def rdoc_task_description
+    'Build RDoc HTML files'
+  end
+
+  ##
+  # Task description for the rerdoc task or its renamed description
+
+  def rerdoc_task_description
+    "Rebuild RDoc HTML files"
+  end
+
   private
 
   def rdoc_target
-    "#{rdoc_dir}/index.html"
+    "#{rdoc_dir}/created.rid"
   end
 
   def rdoc_task_name
@@ -286,4 +327,3 @@ module Rake
 
 end
 # :startdoc:
-

data/lib/rdoc/text.rb

@@ -1,4 +1,4 @@
-# coding: utf-8
+# frozen_string_literal: true
 
 ##
 # For RDoc::Text#to_html
@@ -10,6 +10,21 @@ require 'strscan'
 
 module RDoc::Text
 
+  attr_accessor :language
+
+  ##
+  # Maps markup formats to classes that can parse them.  If the format is
+  # unknown, "rdoc" format is used.
+
+  MARKUP_FORMAT = {
+    'markdown' => RDoc::Markdown,
+    'rdoc'     => RDoc::Markup,
+    'rd'       => RDoc::RD,
+    'tomdoc'   => RDoc::TomDoc,
+  }
+
+  MARKUP_FORMAT.default = RDoc::Markup
+
   ##
   # Maps an encoding to a Hash of characters properly transcoded for that
   # encoding.
@@ -28,7 +43,7 @@ module RDoc::Text
       :open_squote  => encode_fallback('‘', encoding, '\''),
       :trademark    => encode_fallback('®', encoding, '(r)'),
     }
-  end if Object.const_defined? :Encoding
+  end
 
   ##
   # Transcodes +character+ to +encoding+ with a +fallback+ character.
@@ -45,9 +60,11 @@ module RDoc::Text
     expanded = []
 
     text.each_line do |line|
-      line.gsub!(/^(.{8}*?)([^\t\r\n]{0,7})\t/) do
-        "#{$1}#{$2}#{' ' * (8 - $2.size)}"
-      end until line !~ /\t/
+      nil while line.gsub!(/(?:\G|\r)((?:.{8})*?)([^\t\r\n]{0,7})\t/) do
+        r = "#{$1}#{$2}#{' ' * (8 - $2.size)}"
+        r = RDoc::Encoding.change_encoding r, text.encoding
+        r
+      end
 
       expanded << line
     end
@@ -59,22 +76,17 @@ module RDoc::Text
   # Flush +text+ left based on the shortest line
 
   def flush_left text
-    indents = []
+    indent = 9999
 
     text.each_line do |line|
-      indents << (line =~ /[^\s]/ || 9999)
+      line_indent = line =~ /\S/ || 9999
+      indent = line_indent if indent > line_indent
     end
 
-    indent = indents.min
-
-    flush = []
-
-    text.each_line do |line|
-      line[/^ {0,#{indent}}/] = ''
-      flush << line
-    end
+    empty = ''
+    empty = RDoc::Encoding.change_encoding empty, text.encoding
 
-    flush.join
+    text.gsub(/^ {0,#{indent}}/, empty)
   end
 
   ##
@@ -83,9 +95,16 @@ module RDoc::Text
   # Requires the including class to implement #formatter
 
   def markup text
-    document = parse text
-
-    document.accept formatter
+    if @store.rdoc.options
+      locale = @store.rdoc.options.locale
+    else
+      locale = nil
+    end
+    if locale
+      i18n_text = RDoc::I18n::Text.new(text)
+      text = i18n_text.translate(locale)
+    end
+    parse(text).accept formatter
   end
 
   ##
@@ -94,44 +113,39 @@ module RDoc::Text
   def normalize_comment text
     return text if text.empty?
 
-    text = strip_hashes text
-    text = expand_tabs text
-    text = flush_left text
-    strip_newlines text
+    case language
+    when :ruby
+      text = strip_hashes text
+    when :c
+      text = strip_stars text
+    end
+    text = expand_tabs    text
+    text = flush_left     text
+    text = strip_newlines text
+    text
   end
 
   ##
   # Normalizes +text+ then builds a RDoc::Markup::Document from it
 
-  def parse text
+  def parse text, format = 'rdoc'
     return text if RDoc::Markup::Document === text
+    return text.parse if RDoc::Comment === text
 
-    text = normalize_comment text
+    text = normalize_comment text # TODO remove, should not be necessary
 
     return RDoc::Markup::Document.new if text =~ /\A\n*\z/
 
-    RDoc::Markup::Parser.parse text
-  rescue RDoc::Markup::Parser::Error => e
-    $stderr.puts <<-EOF
-While parsing markup, RDoc encountered a #{e.class}:
-
-#{e}
-\tfrom #{e.backtrace.join "\n\tfrom "}
-
----8<---
-#{text}
----8<---
-
-RDoc #{RDoc::VERSION}
-
-Ruby #{RUBY_VERSION}-p#{RUBY_PATCHLEVEL} #{RUBY_RELEASE_DATE}
+    MARKUP_FORMAT[format].parse text
+  end
 
-Please file a bug report with the above information at:
+  ##
+  # The first +limit+ characters of +text+ as HTML
 
-http://rubyforge.org/tracker/?atid=2472&group_id=627&func=browse
+  def snippet text, limit = 100
+    document = parse text
 
-    EOF
-    raise
+    RDoc::Markup::ToHtmlSnippet.new(options, limit).convert document
   end
 
   ##
@@ -139,25 +153,40 @@ http://rubyforge.org/tracker/?atid=2472&group_id=627&func=browse
 
   def strip_hashes text
     return text if text =~ /^(?>\s*)[^\#]/
-    text.gsub(/^\s*(#+)/) { $1.tr '#',' ' }.gsub(/^\s+$/, '')
+
+    empty = ''
+    empty = RDoc::Encoding.change_encoding empty, text.encoding
+
+    text.gsub(/^\s*(#+)/) { $1.tr '#', ' ' }.gsub(/^\s+$/, empty)
   end
 
   ##
   # Strips leading and trailing \n characters from +text+
 
   def strip_newlines text
-    text.gsub(/\A\n*(.*?)\n*\z/m, '\1')
+    text.gsub(/\A\n*(.*?)\n*\z/m) do $1 end # block preserves String encoding
   end
 
   ##
   # Strips /* */ style comments
 
   def strip_stars text
-    text = text.gsub %r%Document-method:\s+[\w:.#]+%, ''
-    text.sub!  %r%/\*+%       do " " * $&.length end
-    text.sub!  %r%\*+/%       do " " * $&.length end
-    text.gsub! %r%^[ \t]*\*%m do " " * $&.length end
-    text.gsub(/^\s+$/, '')
+    return text unless text =~ %r%/\*.*\*/%m
+
+    encoding = text.encoding
+
+    text = text.gsub %r%Document-method:\s+[\w:.#=!?|^&<>~+\-/*\%@`\[\]]+%, ''
+
+    space = ' '
+    space = RDoc::Encoding.change_encoding space, encoding if encoding
+
+    text.sub!  %r%/\*+%       do space * $&.length end
+    text.sub!  %r%\*+/%       do space * $&.length end
+    text.gsub! %r%^[ \t]*\*%m do space * $&.length end
+
+    empty = ''
+    empty = RDoc::Encoding.change_encoding empty, encoding if encoding
+    text.gsub(/^\s+$/, empty)
   end
 
   ##
@@ -165,24 +194,9 @@ http://rubyforge.org/tracker/?atid=2472&group_id=627&func=browse
   # trademark symbols in +text+ to properly encoded characters.
 
   def to_html text
-    if Object.const_defined? :Encoding then
-      html = ''.encode text.encoding
+    html = (''.encode text.encoding).dup
 
-      encoded = RDoc::Text::TO_HTML_CHARACTERS[text.encoding]
-    else
-      html = ''
-      encoded = {
-        :close_dquote => '”',
-        :close_squote => '’',
-        :copyright    => '©',
-        :ellipsis     => '…',
-        :em_dash      => '—',
-        :en_dash      => '–',
-        :open_dquote  => '“',
-        :open_squote  => '‘',
-        :trademark    => '®',
-      }
-    end
+    encoded = RDoc::Text::TO_HTML_CHARACTERS[text.encoding]
 
     s = StringScanner.new text
     insquotes = false
@@ -191,10 +205,10 @@ http://rubyforge.org/tracker/?atid=2472&group_id=627&func=browse
 
     until s.eos? do
       case
-      when s.scan(/<tt>.*?<\/tt>/) then # skip contents of tt
+      when s.scan(/<(tt|code)>.*?<\/\1>/) then # skip contents of tt
         html << s.matched.gsub('\\\\', '\\')
-      when s.scan(/<tt>.*?/) then
-        warn 'mismatched <tt> tag' # TODO signal file/line
+      when s.scan(/<(tt|code)>.*?/) then
+        warn "mismatched <#{s[1]}> tag" # TODO signal file/line
         html << s.matched
       when s.scan(/<[^>]+\/?s*>/) then # skip HTML tags
         html << s.matched
@@ -255,5 +269,36 @@ http://rubyforge.org/tracker/?atid=2472&group_id=627&func=browse
     html
   end
 
-end
+  ##
+  # Wraps +txt+ to +line_len+
+
+  def wrap(txt, line_len = 76)
+    res = []
+    sp = 0
+    ep = txt.length
+
+    while sp < ep
+      # scan back for a space
+      p = sp + line_len - 1
+      if p >= ep
+        p = ep
+      else
+        while p > sp and txt[p] != ?\s
+          p -= 1
+        end
+        if p <= sp
+          p = sp + line_len
+          while p < ep and txt[p] != ?\s
+            p += 1
+          end
+        end
+      end
+      res << txt[sp...p] << "\n"
+      sp = p
+      sp += 1 while sp < ep and txt[sp] == ?\s
+    end
 
+    res.join.strip
+  end
+
+end

data/lib/rdoc/token_stream.rb

@@ -1,3 +1,4 @@
+# frozen_string_literal: true
 ##
 # A TokenStream is a list of tokens, gathered during the parse of some entity
 # (say a method). Entities populate these streams by being registered with the
@@ -7,14 +8,82 @@
 
 module RDoc::TokenStream
 
+  ##
+  # Converts +token_stream+ to HTML wrapping various tokens with
+  # <tt><span></tt> elements. Some tokens types are wrapped in spans
+  # with the given class names. Other token types are not wrapped in spans.
+
+  def self.to_html token_stream
+    starting_title = false
+
+    token_stream.map do |t|
+      next unless t
+
+      style = case t[:kind]
+              when :on_const   then 'ruby-constant'
+              when :on_kw      then 'ruby-keyword'
+              when :on_ivar    then 'ruby-ivar'
+              when :on_cvar    then 'ruby-identifier'
+              when :on_gvar    then 'ruby-identifier'
+              when '=' != t[:text] && :on_op
+                               then 'ruby-operator'
+              when :on_tlambda then 'ruby-operator'
+              when :on_ident   then 'ruby-identifier'
+              when :on_label   then 'ruby-value'
+              when :on_backref, :on_dstring
+                               then 'ruby-node'
+              when :on_comment then 'ruby-comment'
+              when :on_embdoc  then 'ruby-comment'
+              when :on_regexp  then 'ruby-regexp'
+              when :on_tstring then 'ruby-string'
+              when :on_int, :on_float,
+                   :on_rational, :on_imaginary,
+                   :on_heredoc,
+                   :on_symbol, :on_CHAR then 'ruby-value'
+              when :on_heredoc_beg, :on_heredoc_end
+                               then 'ruby-identifier'
+              end
+
+      comment_with_nl = false
+      if :on_comment == t[:kind] or :on_embdoc == t[:kind] or :on_heredoc_end == t[:kind]
+        comment_with_nl = true if "\n" == t[:text][-1]
+        text = t[:text].rstrip
+      else
+        text = t[:text]
+      end
+
+      if :on_ident == t[:kind] && starting_title
+        starting_title = false
+        style = 'ruby-identifier ruby-title'
+      end
+
+      if :on_kw == t[:kind] and 'def' == t[:text]
+        starting_title = true
+      end
+
+      text = CGI.escapeHTML text
+
+      if style then
+        "<span class=\"#{style}\">#{text}</span>#{"\n" if comment_with_nl}"
+      else
+        text
+      end
+    end.join
+  end
+
   ##
   # Adds +tokens+ to the collected tokens
 
-  def add_tokens(*tokens)
-    tokens.flatten.each { |token| @token_stream << token }
+  def add_tokens(tokens)
+    @token_stream.concat(tokens)
   end
 
-  alias add_token add_tokens
+  ##
+  # Adds one +token+ to the collected tokens
+
+  def add_token(token)
+    @token_stream.push(token)
+  end
 
   ##
   # Starts collecting tokens
@@ -43,7 +112,7 @@ module RDoc::TokenStream
   # Returns a string representation of the token stream
 
   def tokens_to_s
-    token_stream.map { |token| token.text }.join ''
+    token_stream.compact.map { |token| token[:text] }.join ''
   end
 
 end