rdoc 6.3.4.1 → 8.0.0

data/lib/rdoc/parser/changelog.rb

@@ -23,7 +23,7 @@ class RDoc::Parser::ChangeLog < RDoc::Parser
   # Continued function listings are joined together as a single entry.
   # Continued descriptions are joined to make a single paragraph.
 
-  def continue_entry_body entry_body, continuation
+  def continue_entry_body(entry_body, continuation)
     return unless last = entry_body.last
 
     if last =~ /\)\s*\z/ and continuation =~ /\A\(/ then
@@ -41,7 +41,7 @@ class RDoc::Parser::ChangeLog < RDoc::Parser
   ##
   # Creates an RDoc::Markup::Document given the +groups+ of ChangeLog entries.
 
-  def create_document groups
+  def create_document(groups)
     doc = RDoc::Markup::Document.new
     doc.omit_headings_below = 2
     doc.file = @top_level
@@ -63,7 +63,7 @@ class RDoc::Parser::ChangeLog < RDoc::Parser
   # Returns a list of ChangeLog entries an RDoc::Markup nodes for the given
   # +entries+.
 
-  def create_entries entries
+  def create_entries(entries)
     out = []
 
     entries.each do |entry, items|
@@ -80,7 +80,7 @@ class RDoc::Parser::ChangeLog < RDoc::Parser
   # Returns an RDoc::Markup::List containing the given +items+ in the
   # ChangeLog
 
-  def create_items items
+  def create_items(items)
     list = RDoc::Markup::List.new :NOTE
 
     items.each do |item|
@@ -100,7 +100,7 @@ class RDoc::Parser::ChangeLog < RDoc::Parser
   ##
   # Groups +entries+ by date.
 
-  def group_entries entries
+  def group_entries(entries)
     @time_cache ||= {}
     entries.group_by do |title, _|
       begin
@@ -193,7 +193,7 @@ class RDoc::Parser::ChangeLog < RDoc::Parser
 
     entries << [entry_name, entry_body] if entry_name
 
-    entries.reject! do |(entry,_)|
+    entries.reject! do |(entry, _)|
       entry == nil
     end
 
@@ -210,18 +210,29 @@ class RDoc::Parser::ChangeLog < RDoc::Parser
     grouped_entries = group_entries entries
 
     doc = create_document grouped_entries
-
-    @top_level.comment = doc
+    comment = RDoc::Comment.new(@content)
+    comment.document = doc
+    @top_level.comment = comment
 
     @top_level
   end
 
+  ##
+  # The extension for Git commit log
+
   module Git
+    ##
+    # Parses auxiliary info.  Currently `base-url` to expand
+    # references is effective.
+
     def parse_info(info)
       /^\s*base-url\s*=\s*(.*\S)/ =~ info
       @base_url = $1
     end
 
+    ##
+    # Parses the entries in the Git commit logs
+
     def parse_entries
       entries = []
 
@@ -244,7 +255,12 @@ class RDoc::Parser::ChangeLog < RDoc::Parser
       entries
     end
 
-    def create_entries entries
+    ##
+    # Returns a list of ChangeLog entries as
+    # RDoc::Parser::ChangeLog::Git::LogEntry list for the given
+    # +entries+.
+
+    def create_entries(entries)
       # git log entries have no strictly itemized style like the old
       # style, just assume Markdown.
       entries.map do |commit, entry|
@@ -258,6 +274,27 @@ class RDoc::Parser::ChangeLog < RDoc::Parser
       def initialize(base, commit, author, email, date, contents)
         case contents
         when String
+          if base&.match(%r[\A([^:/]+:/+[^/]+/)[^/]+/[^/]+/])
+            repo, host = $&, $1
+            contents = contents.dup
+            # base: https://github.com/ruby/ruby/
+            #   Fix #15791 -> Fix [#15791](https://github.com/ruby/ruby/pull/15791)
+            #   GH-15791 -> [GH-15791](https://github.com/ruby/ruby/pull/15791)
+            #   (#15791) -> ([#15791](https://github.com/ruby/ruby/pull/15791))
+            contents.gsub!(/\b(?:(?i:fix(?:e[sd])?) +)\K\#(\d+\b)|\bGH-(\d+)\b|\(\K\#(\d+)(?=\))/) do
+              "[#{$&}](#{repo}pull/#{$1 || $2 || $3})"
+            end
+            # repo#PR, repo@HASH
+            #   ruby/ruby#15791 -> [ruby/ruby#15791](https://github.com/ruby/ruby/pull/15791)
+            #   ruby/ruby@a8a989b6 -> [ruby/ruby@a8a989b6](https://github.com/ruby/ruby/commit/a8a989b6)
+            # ref in branckets is not extended
+            #   [ruby/net-imap#543][ruby/ruby#15791] -> [ruby/net-imap#543][ruby/ruby#15791]
+            contents.gsub!(%r[(?<![-\w#/@]|\]\[)([-\w]+/[-\w]+)(?:@(\h{8,40})|\#(\d+))(?![-\w#/@]|\]\[)]) do
+              path = defined?($2) ? "commit/#{$2}" : "pull/#{$3}"
+              "[#{$&}](#{host}#{$1}/#{path})"
+            end
+          end
+
           contents = RDoc::Markdown.parse(contents).parts.each do |body|
             case body
             when RDoc::Markup::Heading
@@ -277,13 +314,21 @@ class RDoc::Parser::ChangeLog < RDoc::Parser
       end
 
       def aref
+        commit
+      end
+
+      def legacy_aref
         "label-#{commit}"
       end
 
-      def label context = nil
+      def label(context = nil)
         aref
       end
 
+      def legacy_label(context = nil)
+        legacy_aref
+      end
+
       def text
         case base
         when nil
@@ -295,7 +340,7 @@ class RDoc::Parser::ChangeLog < RDoc::Parser
         end + " {#{author}}[mailto:#{email}]"
       end
 
-      def accept visitor
+      def accept(visitor)
         visitor.accept_heading self
         begin
           if visitor.respond_to?(:code_object=)
@@ -312,7 +357,7 @@ class RDoc::Parser::ChangeLog < RDoc::Parser
         end
       end
 
-      def pretty_print q # :nodoc:
+      def pretty_print(q) # :nodoc:
         q.group(2, '[log_entry: ', ']') do
           q.text commit
           q.text ','
@@ -332,4 +377,3 @@ class RDoc::Parser::ChangeLog < RDoc::Parser
     end
   end
 end
-

data/lib/rdoc/parser/markdown.rb

@@ -20,5 +20,3 @@ class RDoc::Parser::Markdown < RDoc::Parser
   end
 
 end
-
-

data/lib/rdoc/parser/rbs.rb

@@ -0,0 +1,275 @@
+# frozen_string_literal: true
+
+require 'rbs'
+
+##
+# Parse RBS signature files as first-class RDoc input.
+
+class RDoc::Parser::RBS < RDoc::Parser
+  RBS_FILE_EXTENSION = /\.rbs$/
+
+  parse_files_matching RBS_FILE_EXTENSION
+
+  def scan
+    _, _, decls = ::RBS::Parser.parse_signature(@content)
+    decls.each do |decl|
+      parse_decl decl, @top_level
+    end
+    @top_level
+  end
+
+  private
+
+  def record_object_location(object, location)
+    object.line = location.start_line if location
+
+    if RDoc::ClassModule === object
+      @top_level.add_to_classes_or_modules object unless
+        @top_level.classes_or_modules.include? object
+    end
+
+    object.record_location @top_level
+    object
+  end
+
+  def rdoc_comment_for(decl)
+    rbs_comment = decl.comment if decl.respond_to?(:comment)
+    return unless rbs_comment
+
+    # TODO: Run RBS comments through RDoc's directive preprocessor so
+    # directives like :nodoc: affect the documented object.
+    comment = RDoc::Comment.new rbs_comment.string, @top_level
+    comment.format = 'markdown'
+    comment
+  end
+
+  def local_module_name(type_name, context)
+    name = type_name.to_s
+    return name if name.start_with?('::')
+
+    namespace_names = context == @top_level ? [] : context.full_name.split('::')
+
+    namespace_names.length.downto(1) do |length|
+      qualified_name = namespace_names.take(length).join('::')
+      if module_name = @top_level.find_module_named("#{qualified_name}::#{name}")
+        return module_name.full_name
+      end
+    end
+
+    name
+  end
+
+  def merge_documentation(object, comment, type_signature_lines)
+    if comment
+      object.comment = if object.comment.empty?
+                         comment
+                       else
+                         merge_comments object, comment
+                       end
+    end
+
+    # TODO: Track RBS-owned documentation overlays so incremental reparsing can
+    # replace stale comments and signatures from the previous RBS parse.
+    object.type_signature_lines ||= type_signature_lines
+  end
+
+  def merge_comments(object, comment)
+    document = RDoc::Markup::Document.new
+    document.concat object.parse(object.comment).parts
+    document << RDoc::Markup::Rule.new(1)
+    document.concat comment.parse.parts
+
+    # Keep this text separator in sync with the Rule node above.
+    merged_comment = RDoc::Comment.new "#{object.comment}\n---\n#{comment}", comment.location
+    merged_comment.format = 'markdown'
+    merged_comment.document = document
+    merged_comment
+  end
+
+  def attr_rw_matches?(existing_rw, new_rw)
+    existing_rw.each_char.any? { |rw| new_rw.include? rw }
+  end
+
+  def merge_attribute_methods(context, name, rw, singleton, comment, type_signature_lines)
+    method_names = []
+    method_names << name if rw.include?('R')
+    method_names << "#{name}=" if rw.include?('W')
+
+    methods = method_names.map { |method_name| context.find_method(method_name, singleton) }
+    methods.compact.each do |method|
+      merge_documentation method, comment, type_signature_lines
+    end
+
+    methods.any?
+  end
+
+  def rdoc_method_name(decl)
+    rbs_constructor_decl?(decl) ? 'new' : decl.name.to_s
+  end
+
+  def rdoc_method_singleton?(decl)
+    # TODO: RBS `self?` methods are :singleton_instance and should add both a
+    # singleton method and a private instance method.
+    rbs_constructor_decl?(decl) || decl.singleton?
+  end
+
+  def rdoc_method_visibility(decl)
+    rbs_constructor_decl?(decl) ? :public : decl.visibility
+  end
+
+  def rbs_constructor_decl?(decl)
+    decl.kind == :instance && decl.name == :initialize
+  end
+
+  def parse_attr_decl(decl, context)
+    rw = case decl
+         when ::RBS::AST::Members::AttrReader
+           'R'
+         when ::RBS::AST::Members::AttrWriter
+           'W'
+         when ::RBS::AST::Members::AttrAccessor
+           'RW'
+         end
+
+    comment = rdoc_comment_for decl
+    type_signature_lines = [decl.type.to_s]
+    name = decl.name.to_s
+    singleton = decl.kind == :singleton
+    if attribute = context.find_attribute(name, singleton)
+      merge_documentation attribute, comment, type_signature_lines if
+        attr_rw_matches? attribute.rw, rw
+      return
+    end
+
+    if merge_attribute_methods(context, name, rw, singleton, comment, type_signature_lines)
+      return
+    end
+
+    attribute = RDoc::Attr.new(
+      name,
+      rw,
+      comment,
+      singleton: singleton
+    )
+    record_object_location attribute, decl.location
+    attribute.type_signature_lines = type_signature_lines
+    context.add_attribute attribute
+    attribute.visibility = decl.visibility if decl.visibility
+  end
+
+  def parse_class_decl(decl, context)
+    owner, name = context.find_or_create_constant_owner_for_path decl.name
+    superclass = decl.super_class&.name&.to_s || '::Object'
+    klass = owner.add_class RDoc::NormalClass, name, superclass
+    record_object_location klass, decl.location
+    comment = rdoc_comment_for decl
+    klass.add_comment comment, @top_level if comment
+
+    decl.members.each { |member| parse_decl member, klass }
+  end
+
+  def parse_constant_decl(decl, context)
+    constant = RDoc::Constant.new decl.name.to_s, decl.type.to_s,
+                                  rdoc_comment_for(decl)
+    record_object_location constant, decl.location
+    context.add_constant constant
+  end
+
+  def parse_decl(decl, context)
+    case decl
+    when ::RBS::AST::Declarations::Class
+      parse_class_decl decl, context
+    when ::RBS::AST::Declarations::Module, ::RBS::AST::Declarations::Interface
+      parse_module_decl decl, context
+    when ::RBS::AST::Declarations::ClassAlias,
+         ::RBS::AST::Declarations::ModuleAlias
+      # TODO: Add RBS class and module aliases to the RDoc store.
+      nil
+    else
+      parse_member_decl decl, context
+    end
+  end
+
+  def parse_extend_decl(decl, context)
+    extend_decl = RDoc::Extend.new local_module_name(decl.name, context),
+                                   rdoc_comment_for(decl)
+    record_object_location extend_decl, decl.location
+    context.add_extend extend_decl
+  end
+
+  def parse_include_decl(decl, context)
+    include_decl = RDoc::Include.new local_module_name(decl.name, context),
+                                    rdoc_comment_for(decl)
+    record_object_location include_decl, decl.location
+    context.add_include include_decl
+  end
+
+  def parse_member_decl(decl, context)
+    case decl
+    when ::RBS::AST::Declarations::Constant
+      parse_constant_decl decl, context
+    when ::RBS::AST::Members::MethodDefinition
+      parse_method_decl decl, context
+    when ::RBS::AST::Members::Alias
+      parse_method_alias_decl decl, context
+    when ::RBS::AST::Members::AttrReader,
+         ::RBS::AST::Members::AttrWriter,
+         ::RBS::AST::Members::AttrAccessor
+      parse_attr_decl decl, context
+    when ::RBS::AST::Members::Include
+      parse_include_decl decl, context
+    when ::RBS::AST::Members::Extend
+      parse_extend_decl decl, context
+    when ::RBS::AST::Members::Private,
+         ::RBS::AST::Members::Public
+      # TODO: Track standalone RBS visibility members.
+      nil
+    end
+  end
+
+  def parse_method_alias_decl(decl, context)
+    alias_def = RDoc::Alias.new(
+      decl.old_name.to_s,
+      decl.new_name.to_s,
+      rdoc_comment_for(decl),
+      singleton: decl.kind == :singleton
+    )
+    record_object_location alias_def, decl.location
+    context.add_alias alias_def
+  end
+
+  def parse_method_decl(decl, context)
+    comment = rdoc_comment_for decl
+    type_signature_lines = decl.overloads.map { |overload| overload.method_type.to_s }
+    method_name = rdoc_method_name(decl)
+    singleton = rdoc_method_singleton?(decl)
+    visibility = rdoc_method_visibility(decl)
+
+    if method = context.find_method(method_name, singleton)
+      merge_documentation method, comment, type_signature_lines
+      return
+    end
+
+    method = RDoc::AnyMethod.new method_name, singleton: singleton
+    record_object_location method, decl.location
+    method.type_signature_lines = type_signature_lines
+
+    if loc = decl.location
+      method.start_collecting_tokens :ruby
+      method.add_token line_no: loc.start_line, char_no: 1, text: loc.source
+    end
+
+    method.comment = comment if comment
+    context.add_method method
+    method.visibility = visibility if visibility
+  end
+
+  def parse_module_decl(decl, context)
+    mod = context.add_module RDoc::NormalModule, decl.name.to_s
+    record_object_location mod, decl.location
+    comment = rdoc_comment_for decl
+    mod.add_comment comment, @top_level if comment
+
+    decl.members.each { |member| parse_decl member, mod }
+  end
+end

data/lib/rdoc/parser/rd.rb

@@ -20,4 +20,3 @@ class RDoc::Parser::RD < RDoc::Parser
   end
 
 end
-