rdoc 6.17.0 → 8.1.0

data/lib/rdoc/code_object/top_level.rb

@@ -1,266 +1,279 @@
 # frozen_string_literal: true
-##
-# A TopLevel context is a representation of the contents of a single file
+module RDoc
+  ##
+  # A TopLevel context is a representation of the contents of a single file
 
-class RDoc::TopLevel < RDoc::Context
+  class TopLevel < Context
 
-  MARSHAL_VERSION = 0 # :nodoc:
+    MARSHAL_VERSION = 0 # :nodoc:
 
-  ##
-  # Relative name of this file
+    ##
+    # Relative name of this file
 
-  attr_accessor :relative_name
+    attr_accessor :relative_name
 
-  ##
-  # Absolute name of this file
+    ##
+    # Absolute name of this file
 
-  attr_accessor :absolute_name
+    attr_accessor :absolute_name
 
-  ##
-  # Base name of this file
+    ##
+    # Base name of this file
 
-  attr_reader :base_name
+    attr_reader :base_name
 
-  ##
-  # Base name of this file without the extension
+    ##
+    # Base name of this file without the extension
 
-  attr_reader :page_name
+    attr_reader :page_name
 
-  ##
-  # All the classes or modules that were declared in
-  # this file. These are assigned to either +#classes_hash+
-  # or +#modules_hash+ once we know what they really are.
+    ##
+    # All the classes or modules that were declared in
+    # this file. These are assigned to either +#classes_hash+
+    # or +#modules_hash+ once we know what they really are.
 
-  attr_reader :classes_or_modules
+    attr_reader :classes_or_modules
 
-  ##
-  # The parser class that processed this file
+    ##
+    # The parser class that processed this file
 
-  attr_reader :parser
+    attr_accessor :parser
 
-  ##
-  # Creates a new TopLevel for the file at +absolute_name+.  If documentation
-  # is being generated outside the source dir +relative_name+ is relative to
-  # the source directory.
-
-  def initialize(absolute_name, relative_name = absolute_name)
-    super()
-    @name = nil
-    @absolute_name = absolute_name
-    @relative_name = relative_name
-    @parser        = nil
-
-    if relative_name
-      @base_name = File.basename(relative_name)
-      @page_name = @base_name.sub(/\.(rb|rdoc|txt|md)\z/i, '')
-    else
-      @base_name = nil
-      @page_name = nil
+    ##
+    # Creates a new TopLevel for the file at +absolute_name+.  If documentation
+    # is being generated outside the source dir +relative_name+ is relative to
+    # the source directory.
+
+    def initialize(absolute_name, relative_name = absolute_name)
+      super()
+      @name = nil
+      @absolute_name = absolute_name
+      @relative_name = relative_name
+      @parser        = nil
+
+      if relative_name
+        @base_name = File.basename(relative_name)
+        @page_name = @base_name.sub(/\.(rb|rdoc|txt|md)\z/i, '')
+      else
+        @base_name = nil
+        @page_name = nil
+      end
+
+      @classes_or_modules = []
     end
 
-    @classes_or_modules = []
-  end
+    ##
+    # An RDoc::TopLevel is equal to another with the same relative_name
 
-  ##
-  # Sets the parser for this toplevel context, also the store.
+    def ==(other)
+      self.class === other and @relative_name == other.relative_name
+    end
 
-  def parser=(val)
-    @parser = val
-    @store.update_parser_of_file(absolute_name, val) if @store
-    @parser
-  end
+    alias eql? ==
 
-  ##
-  # An RDoc::TopLevel is equal to another with the same relative_name
+    ##
+    # Adds +an_alias+ to +Object+ instead of +self+.
 
-  def ==(other)
-    self.class === other and @relative_name == other.relative_name
-  end
+    def add_alias(an_alias)
+      object_class.record_location self
+      return an_alias unless @document_self
+      object_class.add_alias an_alias
+    end
 
-  alias eql? ==
+    ##
+    # Adds +constant+ to +Object+ instead of +self+.
 
-  ##
-  # Adds +an_alias+ to +Object+ instead of +self+.
+    def add_constant(constant)
+      object_class.record_location self
+      return constant unless @document_self
+      object_class.add_constant constant
+    end
 
-  def add_alias(an_alias)
-    object_class.record_location self
-    return an_alias unless @document_self
-    object_class.add_alias an_alias
-  end
+    ##
+    # Adds +include+ to +Object+ instead of +self+.
 
-  ##
-  # Adds +constant+ to +Object+ instead of +self+.
+    def add_include(include)
+      object_class.record_location self
+      return include unless @document_self
+      object_class.add_include include
+    end
 
-  def add_constant(constant)
-    object_class.record_location self
-    return constant unless @document_self
-    object_class.add_constant constant
-  end
+    ##
+    # Adds +method+ to +Object+ instead of +self+.
 
-  ##
-  # Adds +include+ to +Object+ instead of +self+.
+    def add_method(method)
+      object_class.record_location self
+      return method unless @document_self
+      object_class.add_method method
+    end
 
-  def add_include(include)
-    object_class.record_location self
-    return include unless @document_self
-    object_class.add_include include
-  end
+    ##
+    # Adds class or module +mod+. Used in the building phase
+    # by the Ruby parser.
 
-  ##
-  # Adds +method+ to +Object+ instead of +self+.
+    def add_to_classes_or_modules(mod)
+      @classes_or_modules << mod
+    end
 
-  def add_method(method)
-    object_class.record_location self
-    return method unless @document_self
-    object_class.add_method method
-  end
+    alias name base_name
 
-  ##
-  # Adds class or module +mod+. Used in the building phase
-  # by the Ruby parser.
+    ##
+    # See RDoc::TopLevel::find_class_or_module
+    #--
+    # TODO Why do we search through all classes/modules found, not just the
+    #       ones of this instance?
 
-  def add_to_classes_or_modules(mod)
-    @classes_or_modules << mod
-  end
+    def find_class_or_module(name)
+      @store.find_class_or_module name
+    end
 
-  alias name base_name
+    ##
+    # Finds a class or module named +symbol+
 
-  ##
-  # See RDoc::TopLevel::find_class_or_module
-  #--
-  # TODO Why do we search through all classes/modules found, not just the
-  #       ones of this instance?
+    def find_local_symbol(symbol)
+      find_class_or_module(symbol) || super
+    end
 
-  def find_class_or_module(name)
-    @store.find_class_or_module name
-  end
+    ##
+    # Finds a module or class with +name+
 
-  ##
-  # Finds a class or module named +symbol+
+    def find_module_named(name)
+      find_class_or_module(name)
+    end
 
-  def find_local_symbol(symbol)
-    find_class_or_module(symbol) || super
-  end
+    alias get_module_named find_module_named
 
-  ##
-  # Finds a module or class with +name+
+    ##
+    # Returns the relative name of this file
 
-  def find_module_named(name)
-    find_class_or_module(name)
-  end
+    def full_name
+      @relative_name
+    end
 
-  ##
-  # Returns the relative name of this file
+    ##
+    # An RDoc::TopLevel has the same hash as another with the same
+    # relative_name
 
-  def full_name
-    @relative_name
-  end
+    def hash
+      @relative_name.hash
+    end
 
-  ##
-  # An RDoc::TopLevel has the same hash as another with the same
-  # relative_name
+    ##
+    # URL for this with a +prefix+
 
-  def hash
-    @relative_name.hash
-  end
+    def http_url
+      @relative_name.tr('.', '_') + '.html'
+    end
 
-  ##
-  # URL for this with a +prefix+
+    def inspect # :nodoc:
+      "#<%s:0x%x %p modules: %p classes: %p>" % [
+        self.class, object_id,
+        base_name,
+        @modules.map { |n, m| m },
+        @classes.map { |n, c| c }
+      ]
+    end
 
-  def http_url
-    @relative_name.tr('.', '_') + '.html'
-  end
+    ##
+    # Dumps this TopLevel for use by ri.  See also #marshal_load
 
-  def inspect # :nodoc:
-    "#<%s:0x%x %p modules: %p classes: %p>" % [
-      self.class, object_id,
-      base_name,
-      @modules.map { |n, m| m },
-      @classes.map { |n, c| c }
-    ]
-  end
+    def marshal_dump
+      [
+        MARSHAL_VERSION,
+        @relative_name,
+        @parser,
+        parse(@comment),
+      ]
+    end
 
-  ##
-  # Dumps this TopLevel for use by ri.  See also #marshal_load
-
-  def marshal_dump
-    [
-      MARSHAL_VERSION,
-      @relative_name,
-      @parser,
-      parse(@comment),
-    ]
-  end
+    ##
+    # Loads this TopLevel from +array+.
 
-  ##
-  # Loads this TopLevel from +array+.
+    def marshal_load(array) # :nodoc:
+      initialize array[1]
 
-  def marshal_load(array) # :nodoc:
-    initialize array[1]
+      @parser  = array[2]
+      @comment = Comment.from_document array[3]
+    end
 
-    @parser  = array[2]
-    @comment = RDoc::Comment.from_document array[3]
-  end
+    ##
+    # Returns the NormalClass "Object", creating it if not found.
+    #
+    # Records +self+ as a location in "Object".
+
+    def object_class
+      @object_class ||= begin
+        oc = @store.find_class_named('Object') || add_class(NormalClass, 'Object')
+        oc.record_location self
+        oc
+      end
+    end
 
-  ##
-  # Returns the NormalClass "Object", creating it if not found.
-  #
-  # Records +self+ as a location in "Object".
-
-  def object_class
-    @object_class ||= begin
-      oc = @store.find_class_named('Object') || add_class(RDoc::NormalClass, 'Object')
-      oc.record_location self
-      oc
+    ##
+    # Path to this file for use with HTML generator output.
+
+    def path
+      base = if options.main_page == full_name
+               'index.html'
+             else
+               http_url
+             end
+
+      prefix = options.file_path_prefix
+      return base unless prefix
+      File.join(prefix, base)
     end
-  end
 
-  ##
-  # Path to this file for use with HTML generator output.
+    def pretty_print(q) # :nodoc:
+      q.group 2, "[#{self.class}: ", "]" do
+        q.text "base name: #{base_name.inspect}"
+        q.breakable
 
-  def path
-    prefix = options.file_path_prefix
-    return http_url unless prefix
-    File.join(prefix, http_url)
-  end
+        items = @modules.map { |n, m| m }
+        items.concat @modules.map { |n, c| c }
+        q.seplist items do |mod| q.pp mod end
+      end
+    end
+
+    ##
+    # Search record used by RDoc::Generator::JsonIndex
+    #
+    # TODO: Remove this method after dropping the darkfish theme and JsonIndex generator.
+    # Use #search_snippet instead for getting documentation snippets.
+
+    def search_record
+      return unless @parser < Parser::Text
+
+      [
+        page_name,
+        '',
+        page_name,
+        '',
+        path,
+        '',
+        search_snippet,
+      ]
+    end
 
-  def pretty_print(q) # :nodoc:
-    q.group 2, "[#{self.class}: ", "]" do
-      q.text "base name: #{base_name.inspect}"
-      q.breakable
+    ##
+    # Returns an HTML snippet of the comment for search results.
 
-      items = @modules.map { |n, m| m }
-      items.concat @modules.map { |n, c| c }
-      q.seplist items do |mod| q.pp mod end
+    def search_snippet
+      return '' if @comment.empty?
+
+      snippet(@comment)
     end
-  end
 
-  ##
-  # Search record used by RDoc::Generator::JsonIndex
-
-  def search_record
-    return unless @parser < RDoc::Parser::Text
-
-    [
-      page_name,
-      '',
-      page_name,
-      '',
-      path,
-      '',
-      snippet(@comment),
-    ]
-  end
+    ##
+    # Is this TopLevel from a text file instead of a source code file?
 
-  ##
-  # Is this TopLevel from a text file instead of a source code file?
+    def text?
+      @parser and @parser.include? Parser::Text
+    end
 
-  def text?
-    @parser and @parser.include? RDoc::Parser::Text
-  end
+    def to_s # :nodoc:
+      "file #{full_name}"
+    end
 
-  def to_s # :nodoc:
-    "file #{full_name}"
   end
-
 end