rdoc 6.3.4.1 → 8.0.0

data/lib/rdoc/task.rb

@@ -32,7 +32,7 @@ begin
 rescue Gem::LoadError
 end unless defined?(Rake)
 
-require 'rdoc'
+require_relative '../rdoc'
 require 'rake'
 require 'rake/tasklib'
 
@@ -50,13 +50,16 @@ require 'rake/tasklib'
 # [rerdoc]
 #   Rebuild the rdoc files from scratch, even if they are not out of date.
 #
+# [rdoc:coverage]
+#   Print RDoc coverage report for all rdoc files.
+#
 # Simple Example:
 #
 #   require 'rdoc/task'
 #
 #   RDoc::Task.new do |rdoc|
-#     rdoc.main = "README.rdoc"
-#     rdoc.rdoc_files.include("README.rdoc", "lib/**/*.rb")
+#     rdoc.main = "README.md"
+#     rdoc.rdoc_files.include("README.md", "lib/**/*.rb")
 #   end
 #
 # The +rdoc+ object passed to the block is an RDoc::Task object. See the
@@ -71,8 +74,8 @@ require 'rake/tasklib'
 #   require 'rdoc/task'
 #
 #   RDoc::Task.new :rdoc_dev do |rdoc|
-#     rdoc.main = "README.doc"
-#     rdoc.rdoc_files.include("README.rdoc", "lib/**/*.rb")
+#     rdoc.main = "README.md"
+#     rdoc.rdoc_files.include("README.md", "lib/**/*.rb")
 #     rdoc.options << "--all"
 #   end
 #
@@ -90,8 +93,8 @@ require 'rake/tasklib'
 #   RDoc::Task.new(:rdoc => "rdoc", :clobber_rdoc => "rdoc:clean",
 #                  :rerdoc => "rdoc:force")
 #
-# This will create the tasks <tt>:rdoc</tt>, <tt>:rdoc:clean</tt> and
-# <tt>:rdoc:force</tt>.
+# This will create the tasks <tt>:rdoc</tt>, <tt>:rdoc:clean</tt>,
+# <tt>:rdoc:force</tt>, and <tt>:rdoc:coverage</tt>.
 
 class RDoc::Task < Rake::TaskLib
 
@@ -101,9 +104,8 @@ class RDoc::Task < Rake::TaskLib
   attr_accessor :name
 
   ##
-  # Comment markup format.  rdoc, rd and tomdoc are supported.  (default is
-  # 'rdoc')
-
+  # The markup format; one of: +rdoc+ (the default), +markdown+, +rd+, +tomdoc+.
+  # See {Markup Formats}[rdoc-ref:RDoc::Markup@Markup+Formats].
   attr_accessor :markup
 
   ##
@@ -152,7 +154,7 @@ 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
+  def initialize(name = :rdoc) # :yield: self
     defaults
 
     check_names name
@@ -168,7 +170,7 @@ class RDoc::Task < Rake::TaskLib
   # 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
+  def check_names(names)
     return unless Hash === names
 
     invalid_options =
@@ -200,21 +202,6 @@ class RDoc::Task < Rake::TaskLib
     @options = []
   end
 
-  ##
-  # All source is inline now.  This method is deprecated
-
-  def inline_source # :nodoc:
-    warn "RDoc::Task#inline_source is deprecated"
-    true
-  end
-
-  ##
-  # All source is inline now.  This method is deprecated
-
-  def inline_source=(value) # :nodoc:
-    warn "RDoc::Task#inline_source is deprecated"
-  end
-
   ##
   # Create the tasks defined by this task lib.
 
@@ -248,6 +235,27 @@ class RDoc::Task < Rake::TaskLib
       RDoc::RDoc.new.document args
     end
 
+    namespace rdoc_task_name do
+      desc coverage_task_description
+      task coverage_task_name do
+        @before_running_rdoc.call if @before_running_rdoc
+        opts = option_list << "-C"
+        args = opts + @rdoc_files
+
+        $stderr.puts "rdoc #{args.join ' '}" if Rake.application.options.trace
+        RDoc::RDoc.new.document args
+      end
+
+      desc server_task_description
+      task "server" do
+        @before_running_rdoc.call if @before_running_rdoc
+        args = option_list + ["--server"] + @rdoc_files
+
+        $stderr.puts "rdoc #{args.join ' '}" if Rake.application.options.trace
+        RDoc::RDoc.new.document args
+      end
+    end
+
     self
   end
 
@@ -288,6 +296,20 @@ class RDoc::Task < Rake::TaskLib
     "Rebuild RDoc HTML files"
   end
 
+  ##
+  # Task description for the coverage task or its renamed description
+
+  def coverage_task_description
+    "Print RDoc coverage report"
+  end
+
+  ##
+  # Task description for the server task
+
+  def server_task_description
+    "Start a live-reloading documentation server"
+  end
+
   private
 
   def rdoc_target
@@ -315,6 +337,10 @@ class RDoc::Task < Rake::TaskLib
     end
   end
 
+  def coverage_task_name
+    "coverage"
+  end
+
 end
 
 # :stopdoc:
@@ -323,7 +349,7 @@ module Rake
   ##
   # For backwards compatibility
 
-  RDocTask = RDoc::Task
+  RDocTask = RDoc::Task # :nodoc:
 
 end
 # :startdoc:

data/lib/rdoc/text.rb

@@ -10,6 +10,10 @@ require 'strscan'
 
 module RDoc::Text
 
+  ##
+  # The language for this text.  This affects stripping comments
+  # markers.
+
   attr_accessor :language
 
   ##
@@ -25,38 +29,10 @@ module RDoc::Text
 
   MARKUP_FORMAT.default = RDoc::Markup
 
-  ##
-  # Maps an encoding to a Hash of characters properly transcoded for that
-  # encoding.
-  #
-  # See also encode_fallback.
-
-  TO_HTML_CHARACTERS = Hash.new do |h, encoding|
-    h[encoding] = {
-      :close_dquote => encode_fallback('”', encoding, '"'),
-      :close_squote => encode_fallback('’', encoding, '\''),
-      :copyright    => encode_fallback('©', encoding, '(c)'),
-      :ellipsis     => encode_fallback('…', encoding, '...'),
-      :em_dash      => encode_fallback('—', encoding, '---'),
-      :en_dash      => encode_fallback('–', encoding, '--'),
-      :open_dquote  => encode_fallback('“', encoding, '"'),
-      :open_squote  => encode_fallback('‘', encoding, '\''),
-      :trademark    => encode_fallback('®', encoding, '(r)'),
-    }
-  end
-
-  ##
-  # Transcodes +character+ to +encoding+ with a +fallback+ character.
-
-  def self.encode_fallback character, encoding, fallback
-    character.encode(encoding, :fallback => { character => fallback },
-                     :undef => :replace, :replace => fallback)
-  end
-
   ##
   # Expands tab characters in +text+ to eight spaces
 
-  def expand_tabs text
+  module_function def expand_tabs(text)
     expanded = []
 
     text.each_line do |line|
@@ -75,7 +51,7 @@ module RDoc::Text
   ##
   # Flush +text+ left based on the shortest line
 
-  def flush_left text
+  def flush_left(text)
     indent = 9999
 
     text.each_line do |line|
@@ -94,9 +70,9 @@ module RDoc::Text
   #
   # Requires the including class to implement #formatter
 
-  def markup text
-    if @store.rdoc.options
-      locale = @store.rdoc.options.locale
+  def markup(text)
+    if @store.options
+      locale = @store.options.locale
     else
       locale = nil
     end
@@ -110,7 +86,7 @@ module RDoc::Text
   ##
   # Strips hashes, expands tabs then flushes +text+ to the left
 
-  def normalize_comment text
+  def normalize_comment(text)
     return text if text.empty?
 
     case language
@@ -128,7 +104,7 @@ module RDoc::Text
   ##
   # Normalizes +text+ then builds a RDoc::Markup::Document from it
 
-  def parse text, format = 'rdoc'
+  def parse(text, format = 'rdoc')
     return text if RDoc::Markup::Document === text
     return text.parse if RDoc::Comment === text
 
@@ -142,16 +118,16 @@ module RDoc::Text
   ##
   # The first +limit+ characters of +text+ as HTML
 
-  def snippet text, limit = 100
+  def snippet(text, limit = 100)
     document = parse text
 
-    RDoc::Markup::ToHtmlSnippet.new(options, limit).convert document
+    RDoc::Markup::ToHtmlSnippet.new(limit).convert document
   end
 
   ##
   # Strips leading # characters from +text+
 
-  def strip_hashes text
+  def strip_hashes(text)
     return text if text =~ /^(?>\s*)[^\#]/
 
     empty = ''
@@ -163,14 +139,14 @@ module RDoc::Text
   ##
   # Strips leading and trailing \n characters from +text+
 
-  def strip_newlines text
+  def strip_newlines(text)
     text.gsub(/\A\n*(.*?)\n*\z/m) do $1 end # block preserves String encoding
   end
 
   ##
   # Strips /* */ style comments
 
-  def strip_stars text
+  def strip_stars(text)
     return text unless text =~ %r%/\*.*\*/%m
 
     encoding = text.encoding
@@ -189,86 +165,6 @@ module RDoc::Text
     text.gsub(/^\s+$/, empty)
   end
 
-  ##
-  # Converts ampersand, dashes, ellipsis, quotes, copyright and registered
-  # trademark symbols in +text+ to properly encoded characters.
-
-  def to_html text
-    html = (''.encode text.encoding).dup
-
-    encoded = RDoc::Text::TO_HTML_CHARACTERS[text.encoding]
-
-    s = StringScanner.new text
-    insquotes = false
-    indquotes = false
-    after_word = nil
-
-    until s.eos? do
-      case
-      when s.scan(/<(tt|code)>.*?<\/\1>/) then # skip contents of tt
-        html << s.matched.gsub('\\\\', '\\')
-      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
-      when s.scan(/\\(\S)/) then # unhandled suppressed crossref
-        html << s[1]
-        after_word = nil
-      when s.scan(/\.\.\.(\.?)/) then
-        html << s[1] << encoded[:ellipsis]
-        after_word = nil
-      when s.scan(/\(c\)/) then
-        html << encoded[:copyright]
-        after_word = nil
-      when s.scan(/\(r\)/) then
-        html << encoded[:trademark]
-        after_word = nil
-      when s.scan(/---/) then
-        html << encoded[:em_dash]
-        after_word = nil
-      when s.scan(/--/) then
-        html << encoded[:en_dash]
-        after_word = nil
-      when s.scan(/&quot;|"/) then
-        html << encoded[indquotes ? :close_dquote : :open_dquote]
-        indquotes = !indquotes
-        after_word = nil
-      when s.scan(/``/) then # backtick double quote
-        html << encoded[:open_dquote]
-        after_word = nil
-      when s.scan(/''/) then # tick double quote
-        html << encoded[:close_dquote]
-        after_word = nil
-      when s.scan(/'/) then # single quote
-        if insquotes
-          html << encoded[:close_squote]
-          insquotes = false
-        elsif after_word
-          # Mary's dog, my parents' house: do not start paired quotes
-          html << encoded[:close_squote]
-        else
-          html << encoded[:open_squote]
-          insquotes = true
-        end
-
-        after_word = nil
-      else # advance to the next potentially significant character
-        match = s.scan(/.+?(?=[<\\.("'`&-])/) #"
-
-        if match then
-          html << match
-          after_word = match =~ /\w$/
-        else
-          html << s.rest
-          break
-        end
-      end
-    end
-
-    html
-  end
-
   ##
   # Wraps +txt+ to +line_len+
 
@@ -301,4 +197,48 @@ module RDoc::Text
     res.join.strip
   end
 
+  ##
+  # Character class to be separated by a space when concatenating
+  # lines.
+
+  SPACE_SEPARATED_LETTER_CLASS = /[\p{Nd}\p{Lc}\p{Pc}]|[!-~&&\W]/
+
+  ##
+  # Converts +text+ to a GitHub-style anchor ID:
+  # - Lowercase
+  # - Remove characters that aren't alphanumeric, space, or hyphen
+  # - Replace spaces with hyphens
+  #
+  # Examples:
+  #   "Hello World"  -> "hello-world"
+  #   "Foo::Bar"     -> "foobar"
+  #   "What's New?"  -> "whats-new"
+
+  module_function def to_anchor(text)
+    text.downcase.gsub(/[^a-z0-9 \-]/, '').gsub(' ', '-')
+  end
+
+  ##
+  # Decodes a label that may be in legacy RDoc format where CGI.escape was
+  # applied and then '%' was replaced with '-'. Converts '+' to space,
+  # then reverses -XX hex encoding for non-alphanumeric characters.
+  #
+  # Labels in new format pass through unchanged because -XX patterns that
+  # decode to alphanumeric characters are left as-is (CGI.escape never
+  # encodes alphanumerics).
+  #
+  # Examples:
+  #   "What-27s+Here"  -> "What's Here"  (legacy: -27 is apostrophe)
+  #   "Foo-3A-3ABar"   -> "Foo::Bar"     (legacy: -3A is colon)
+  #   "Whats-Here"     -> "Whats-Here"   (new format, unchanged)
+
+  module_function def decode_legacy_label(label)
+    label = label.tr('+', ' ')
+    label.gsub!(/-([0-7][0-9A-F])/) do
+      char = [$1.hex].pack('C')
+      char.match?(/[a-zA-Z0-9]/) ? $& : char
+    end
+    label
+  end
+
 end

data/lib/rdoc/token_stream.rb

@@ -1,4 +1,5 @@
 # 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
@@ -13,58 +14,32 @@ module RDoc::TokenStream
   # <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
-
+  def self.to_html(token_stream)
     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'
+              when :operator   then 'ruby-operator'
+              when :keyword    then 'ruby-keyword'
+              when :constant   then 'ruby-constant'
+              when :ivar       then 'ruby-ivar'
+              when :comment    then 'ruby-comment'
+              when :value      then 'ruby-value'
+              when :string     then 'ruby-string'
+              when :symbol     then 'ruby-value'
+              when :x_string   then 'ruby-string'
+              when :regexp     then 'ruby-regexp'
+              when :identifier 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 = t[:text]
 
       text = CGI.escapeHTML text
 
       if style then
-        "<span class=\"#{style}\">#{text}</span>#{"\n" if comment_with_nl}"
+        end_with_newline = text.end_with?("\n")
+        text = text.chomp if end_with_newline
+        "<span class=\"#{style}\">#{text}</span>#{"\n" if end_with_newline}"
       else
         text
       end
@@ -87,9 +62,11 @@ module RDoc::TokenStream
 
   ##
   # Starts collecting tokens
+  #
 
-  def collect_tokens
+  def collect_tokens(language)
     @token_stream = []
+    @token_stream_language = language
   end
 
   alias start_collecting_tokens collect_tokens
@@ -112,8 +89,16 @@ module RDoc::TokenStream
   # Returns a string representation of the token stream
 
   def tokens_to_s
-    token_stream.compact.map { |token| token[:text] }.join ''
+    (token_stream or return '').compact.map { |token| token[:text] }.join ''
   end
 
-end
+  ##
+  # Returns the source language of the token stream as a string
+  #
+  # Returns 'c' or 'ruby'
 
+  def source_language
+    @token_stream_language == :c ? 'c' : 'ruby'
+  end
+
+end

data/lib/rdoc/tom_doc.rb

@@ -3,13 +3,7 @@
 
 # A parser for TomDoc based on TomDoc 1.0.0-rc1 (02adef9b5a)
 #
-# The TomDoc specification can be found at:
-#
-# http://tomdoc.org
-#
-# The latest version of the TomDoc specification can be found at:
-#
-# https://github.com/mojombo/tomdoc/blob/master/tomdoc.md
+# The TomDoc specification can be found at http://tomdoc.org.
 #
 # To choose TomDoc as your only default format see RDoc::Options@Saved+Options
 # for instructions on setting up a <code>.rdoc_options</code> file to store
@@ -55,7 +49,7 @@ class RDoc::TomDoc < RDoc::Markup::Parser
       next unless code_object and
                   RDoc::Comment === comment and comment.format == 'tomdoc'
 
-      comment.text.gsub!(/(\A\s*# )(Public|Internal|Deprecated):\s+/) do
+      comment.text.gsub!(/\A(\s*# |)(Public|Internal|Deprecated):\s+/) do
         section = code_object.add_section $2
         code_object.temporary_section = section
 
@@ -81,7 +75,7 @@ class RDoc::TomDoc < RDoc::Markup::Parser
   #
   # Returns an RDoc::Markup::Document representing the TomDoc format.
 
-  def self.parse text
+  def self.parse(text)
     parser = new
 
     parser.tokenize text
@@ -97,7 +91,7 @@ class RDoc::TomDoc < RDoc::Markup::Parser
   #
   # Returns a String containing the signature and nil if not
 
-  def self.signature comment
+  def self.signature(comment)
     return unless comment.tomdoc?
 
     document = comment.parse
@@ -140,7 +134,7 @@ class RDoc::TomDoc < RDoc::Markup::Parser
   #
   # Returns an RDoc::Markup::Heading
 
-  def build_heading level
+  def build_heading(level)
     heading = super
 
     @section = heading.text
@@ -156,7 +150,7 @@ class RDoc::TomDoc < RDoc::Markup::Parser
   #
   # Returns an RDoc::Markup::Verbatim
 
-  def build_verbatim margin
+  def build_verbatim(margin)
     verbatim = super
 
     verbatim.format = :ruby if @section == 'Examples'
@@ -170,7 +164,7 @@ class RDoc::TomDoc < RDoc::Markup::Parser
   #
   # Returns an RDoc::Markup::Paragraph.
 
-  def build_paragraph margin
+  def build_paragraph(margin)
     p :paragraph_start => margin if @debug
 
     paragraph = RDoc::Markup::Paragraph.new
@@ -210,7 +204,7 @@ class RDoc::TomDoc < RDoc::Markup::Parser
   ##
   # Detects a section change to "Returns" and adds a heading
 
-  def parse_text parent, indent # :nodoc:
+  def parse_text(parent, indent) # :nodoc:
     paragraph = build_paragraph indent
 
     if false == @seen_returns and 'Returns' == @section then
@@ -228,7 +222,7 @@ class RDoc::TomDoc < RDoc::Markup::Parser
   #
   # Returns self.
 
-  def tokenize text
+  def tokenize(text)
     text = text.sub(/\A(Public|Internal|Deprecated):\s+/, '')
 
     setup_scanner text

data/lib/rdoc/version.rb

@@ -1,8 +1,10 @@
+# frozen_string_literal: true
+
 module RDoc
 
   ##
   # RDoc version you are using
 
-  VERSION = '6.3.4.1'
+  VERSION = '8.0.0'
 
 end