rdoc 8.0.0 → 8.1.0

data/lib/rdoc/parser/markdown.rb

@@ -1,22 +1,26 @@
 # frozen_string_literal: true
-##
-# Parse a Markdown format file.  The parsed RDoc::Markup::Document is attached
-# as a file comment.
+module RDoc
+  class Parser
+    ##
+    # Parse a Markdown format file.  The parsed RDoc::Markup::Document is attached
+    # as a file comment.
 
-class RDoc::Parser::Markdown < RDoc::Parser
+    class Markdown < Parser
 
-  include RDoc::Parser::Text
+      include Parser::Text
 
-  parse_files_matching(/\.(md|markdown)(?:\.[^.]+)?$/)
+      parse_files_matching(/\.(md|markdown)(?:\.[^.]+)?$/)
 
-  ##
-  # Creates an Markdown-format TopLevel for the given file.
+      ##
+      # Creates an Markdown-format TopLevel for the given file.
 
-  def scan
-    comment = RDoc::Comment.new @content, @top_level
-    comment.format = 'markdown'
+      def scan
+        comment = Comment.new @content, @top_level
+        comment.format = 'markdown'
 
-    @top_level.comment = comment
-  end
+        @top_level.comment = comment
+      end
 
+    end
+  end
 end

data/lib/rdoc/parser/rbs.rb

@@ -2,274 +2,278 @@
 
 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
+module RDoc
+  class Parser
+    ##
+    # Parse RBS signature files as first-class RDoc input.
+
+    class RBS < 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
 
-    object.record_location @top_level
-    object
-  end
+    private
 
-  def rdoc_comment_for(decl)
-    rbs_comment = decl.comment if decl.respond_to?(:comment)
-    return unless rbs_comment
+      def record_object_location(object, location)
+        object.line = location.start_line if location
 
-    # 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
+        if ClassModule === object
+          @top_level.add_to_classes_or_modules object unless
+            @top_level.classes_or_modules.include? object
+        end
 
-  def local_module_name(type_name, context)
-    name = type_name.to_s
-    return name if name.start_with?('::')
+        object.record_location @top_level
+        object
+      end
 
-    namespace_names = context == @top_level ? [] : context.full_name.split('::')
+      def rdoc_comment_for(decl)
+        rbs_comment = decl.comment if decl.respond_to?(:comment)
+        return unless rbs_comment
 
-    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
+        # TODO: Run RBS comments through RDoc's directive preprocessor so
+        # directives like :nodoc: affect the documented object.
+        comment = Comment.new rbs_comment.string, @top_level
+        comment.format = 'markdown'
+        comment
       end
-    end
 
-    name
-  end
+      def local_module_name(type_name, context)
+        name = type_name.to_s
+        return name if name.start_with?('::')
 
-  def merge_documentation(object, comment, type_signature_lines)
-    if comment
-      object.comment = if object.comment.empty?
-                         comment
-                       else
-                         merge_comments object, comment
-                       end
-    end
+        namespace_names = context == @top_level ? [] : context.full_name.split('::')
 
-    # 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
+        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
 
-  def attr_rw_matches?(existing_rw, new_rw)
-    existing_rw.each_char.any? { |rw| new_rw.include? rw }
-  end
+        name
+      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')
+      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
 
-    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
+      def merge_comments(object, comment)
+        document = Markup::Document.new
+        document.concat object.parse(object.comment).parts
+        document << Markup::Rule.new(1)
+        document.concat comment.parse.parts
+
+        # Keep this text separator in sync with the Rule node above.
+        merged_comment = Comment.new "#{object.comment}\n---\n#{comment}", comment.location
+        merged_comment.format = 'markdown'
+        merged_comment.document = document
+        merged_comment
+      end
 
-    methods.any?
-  end
+      def attr_rw_matches?(existing_rw, new_rw)
+        existing_rw.each_char.any? { |rw| new_rw.include? rw }
+      end
 
-  def rdoc_method_name(decl)
-    rbs_constructor_decl?(decl) ? 'new' : decl.name.to_s
-  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')
 
-  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
+        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
 
-  def rdoc_method_visibility(decl)
-    rbs_constructor_decl?(decl) ? :public : decl.visibility
-  end
+        methods.any?
+      end
 
-  def rbs_constructor_decl?(decl)
-    decl.kind == :instance && decl.name == :initialize
-  end
+      def rdoc_method_name(decl)
+        rbs_constructor_decl?(decl) ? 'new' : decl.name.to_s
+      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
+      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
 
-    if merge_attribute_methods(context, name, rw, singleton, comment, type_signature_lines)
-      return
-    end
+      def rdoc_method_visibility(decl)
+        rbs_constructor_decl?(decl) ? :public : decl.visibility
+      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 rbs_constructor_decl?(decl)
+        decl.kind == :instance && decl.name == :initialize
+      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
+      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 = Attr.new(
+          name,
+          rw,
+          comment,
+          singleton: singleton
+        )
+        record_object_location attribute, decl.location
+        attribute.type_signature_lines = type_signature_lines
+        attribute.visibility = decl.visibility if decl.visibility
+        context.add_attribute attribute
+      end
 
-    decl.members.each { |member| parse_decl member, klass }
-  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 NormalClass, name, superclass
+        record_object_location klass, decl.location
+        comment = rdoc_comment_for decl
+        klass.add_comment comment, @top_level if comment
 
-  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
+        decl.members.each { |member| parse_decl member, klass }
+      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_constant_decl(decl, context)
+        constant = 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_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_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_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_extend_decl(decl, context)
+        extend_decl = 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_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_include_decl(decl, context)
+        include_decl = 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_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_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_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)
+      def parse_method_alias_decl(decl, context)
+        alias_def = 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
 
-    if method = context.find_method(method_name, singleton)
-      merge_documentation method, comment, type_signature_lines
-      return
-    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 = 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
+        method.visibility = visibility if visibility
+        context.add_method method
+      end
 
-    method = RDoc::AnyMethod.new method_name, singleton: singleton
-    record_object_location method, decl.location
-    method.type_signature_lines = type_signature_lines
+      def parse_module_decl(decl, context)
+        mod = context.add_module NormalModule, decl.name.to_s
+        record_object_location mod, decl.location
+        comment = rdoc_comment_for decl
+        mod.add_comment comment, @top_level if comment
 
-    if loc = decl.location
-      method.start_collecting_tokens :ruby
-      method.add_token line_no: loc.start_line, char_no: 1, text: loc.source
+        decl.members.each { |member| parse_decl member, mod }
+      end
     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

@@ -1,22 +1,26 @@
 # frozen_string_literal: true
-##
-# Parse a RD format file.  The parsed RDoc::Markup::Document is attached as a
-# file comment.
+module RDoc
+  class Parser
+    ##
+    # Parse a RD format file.  The parsed RDoc::Markup::Document is attached as a
+    # file comment.
 
-class RDoc::Parser::RD < RDoc::Parser
+    class RD < Parser
 
-  include RDoc::Parser::Text
+      include Parser::Text
 
-  parse_files_matching(/\.rd(?:\.[^.]+)?$/)
+      parse_files_matching(/\.rd(?:\.[^.]+)?$/)
 
-  ##
-  # Creates an rd-format TopLevel for the given file.
+      ##
+      # Creates an rd-format TopLevel for the given file.
 
-  def scan
-    comment = RDoc::Comment.new @content, @top_level
-    comment.format = 'rd'
+      def scan
+        comment = Comment.new @content, @top_level
+        comment.format = 'rd'
 
-    @top_level.comment = comment
-  end
+        @top_level.comment = comment
+      end
 
+    end
+  end
 end