rdoc 7.2.0 → 8.1.0

data/lib/rdoc/code_object.rb

@@ -1,395 +1,395 @@
 # frozen_string_literal: true
-##
-# Base class for the RDoc code tree.
-#
-# We contain the common stuff for contexts (which are containers) and other
-# elements (methods, attributes and so on)
-#
-# Here's the tree of the CodeObject subclasses:
-#
-# * RDoc::Context
-#   * RDoc::TopLevel
-#   * RDoc::ClassModule
-#     * RDoc::AnonClass (never used so far)
-#     * RDoc::NormalClass
-#     * RDoc::NormalModule
-#     * RDoc::SingleClass
-# * RDoc::MethodAttr
-#   * RDoc::Attr
-#   * RDoc::AnyMethod
-#     * RDoc::GhostMethod
-#     * RDoc::MetaMethod
-# * RDoc::Alias
-# * RDoc::Constant
-# * RDoc::Require
-# * RDoc::Mixin
-#   * RDoc::Include
-#   * RDoc::Extend
-
-class RDoc::CodeObject
-
-  include RDoc::Text
-
+module RDoc
   ##
-  # Our comment
+  # Base class for the RDoc code tree.
+  #
+  # We contain the common stuff for contexts (which are containers) and other
+  # elements (methods, attributes and so on)
+  #
+  # Here's the tree of the CodeObject subclasses:
+  #
+  # * RDoc::Context
+  #   * RDoc::TopLevel
+  #   * RDoc::ClassModule
+  #     * RDoc::NormalClass
+  #     * RDoc::NormalModule
+  #     * RDoc::SingleClass
+  # * RDoc::MethodAttr
+  #   * RDoc::Attr
+  #   * RDoc::AnyMethod
+  # * RDoc::Alias
+  # * RDoc::Constant
+  # * RDoc::Require
+  # * RDoc::Mixin
+  #   * RDoc::Include
+  #   * RDoc::Extend
 
-  attr_reader :comment
+  class CodeObject
 
-  ##
-  # Do we document our children?
+    include Text
 
-  attr_reader :document_children
+    ##
+    # Our comment
 
-  ##
-  # Do we document ourselves?
+    attr_reader :comment
 
-  attr_reader :document_self
+    ##
+    # Do we document our children?
 
-  ##
-  # Are we done documenting (ie, did we come across a :enddoc:)?
+    attr_reader :document_children
 
-  attr_reader :done_documenting
+    ##
+    # Do we document ourselves?
 
-  ##
-  # Which file this code object was defined in
+    attr_reader :document_self
 
-  attr_reader :file
+    ##
+    # Are we done documenting (ie, did we come across a :enddoc:)?
 
-  ##
-  # Force documentation of this CodeObject
+    attr_reader :done_documenting
 
-  attr_reader :force_documentation
+    ##
+    # Which file this code object was defined in
 
-  ##
-  # Line in #file where this CodeObject was defined
+    attr_reader :file
 
-  attr_accessor :line
+    ##
+    # Force documentation of this CodeObject
 
-  ##
-  # Hash of arbitrary metadata for this CodeObject
+    attr_reader :force_documentation
 
-  attr_reader :metadata
+    ##
+    # Line in #file where this CodeObject was defined
 
-  ##
-  # Sets the parent CodeObject
+    attr_accessor :line
 
-  attr_writer :parent
+    ##
+    # Hash of arbitrary metadata for this CodeObject
 
-  ##
-  # Did we ever receive a +:nodoc:+ directive?
+    attr_reader :metadata
 
-  attr_reader :received_nodoc
+    ##
+    # Sets the parent CodeObject
 
-  ##
-  # Set the section this CodeObject is in
+    attr_writer :parent
 
-  attr_writer :section
+    ##
+    # Did we ever receive a +:nodoc:+ directive?
 
-  ##
-  # The RDoc::Store for this object.
+    attr_reader :received_nodoc
 
-  attr_reader :store
+    ##
+    # Set the section this CodeObject is in
 
-  ##
-  # When mixed-in to a class, this points to the Context in which it was originally defined.
+    attr_writer :section
 
-  attr_accessor :mixin_from
+    ##
+    # The RDoc::Store for this object.
 
-  ##
-  # Creates a new CodeObject that will document itself and its children
-
-  def initialize
-    @metadata         = {}
-    @comment          = ''
-    @parent           = nil
-    @parent_name      = nil # for loading
-    @parent_class     = nil # for loading
-    @section          = nil
-    @section_title    = nil # for loading
-    @file             = nil
-    @full_name        = nil
-    @store            = nil
-    @track_visibility = true
-    @mixin_from       = nil
-
-    initialize_visibility
-  end
+    attr_reader :store
 
-  ##
-  # Initializes state for visibility of this CodeObject and its children.
-
-  def initialize_visibility # :nodoc:
-    @document_children   = true
-    @document_self       = true
-    @done_documenting    = false
-    @force_documentation = false
-    @received_nodoc      = false
-    @ignored             = false
-    @suppressed          = false
-    @track_visibility    = true
-  end
+    ##
+    # When mixed-in to a class, this points to the Context in which it was originally defined.
 
-  ##
-  # Replaces our comment with +comment+, unless it is empty.
-
-  def comment=(comment)
-    @comment = case comment
-               when NilClass               then ''
-               when RDoc::Comment          then comment.normalize
-               else
-                 if comment and not comment.empty? then
-                   normalize_comment comment
-                 else
-                   # HACK correct fix is to have #initialize create @comment
-                   #      with the correct encoding
-                   if String === @comment and @comment.empty? then
-                     @comment = RDoc::Encoding.change_encoding @comment, comment.encoding
-                   end
-                   @comment
-                 end
-               end
-  end
+    attr_accessor :mixin_from
 
-  ##
-  # Should this CodeObject be displayed in output?
-  #
-  # A code object should be displayed if:
-  #
-  # * The item didn't have a nodoc or wasn't in a container that had nodoc
-  # * The item wasn't ignored
-  # * The item has documentation and was not suppressed
+    ##
+    # Creates a new CodeObject that will document itself and its children
 
-  def display?
-    @document_self and not @ignored and
-      (documented? or not @suppressed)
-  end
+    def initialize
+      @metadata         = {}
+      @comment          = ''
+      @parent           = nil
+      @parent_name      = nil # for loading
+      @parent_class     = nil # for loading
+      @section          = nil
+      @section_title    = nil # for loading
+      @file             = nil
+      @full_name        = nil
+      @store            = nil
+      @track_visibility = true
+      @mixin_from       = nil
 
-  ##
-  # Enables or disables documentation of this CodeObject's children unless it
-  # has been turned off by :enddoc:
+      initialize_visibility
+    end
 
-  def document_children=(document_children)
-    return unless @track_visibility
+    ##
+    # Initializes state for visibility of this CodeObject and its children.
+
+    def initialize_visibility # :nodoc:
+      @document_children   = true
+      @document_self       = true
+      @done_documenting    = false
+      @force_documentation = false
+      @received_nodoc      = false
+      @ignored             = false
+      @suppressed          = false
+      @track_visibility    = true
+    end
 
-    @document_children = document_children unless @done_documenting
-  end
+    ##
+    # Replaces our comment with +comment+, unless it is empty.
 
-  ##
-  # Enables or disables documentation of this CodeObject unless it has been
-  # turned off by :enddoc:.  If the argument is +nil+ it means the
-  # documentation is turned off by +:nodoc:+.
+    def comment=(comment)
+      @comment = case comment
+                 when NilClass               then ''
+                 when Comment          then comment.normalize
+                 else
+                   if comment and not comment.empty?
+                     normalize_comment comment
+                   else
+                     # HACK correct fix is to have #initialize create @comment
+                     #      with the correct encoding
+                     if String === @comment and @comment.empty?
+                       @comment = Encoding.change_encoding @comment, comment.encoding
+                     end
+                     @comment
+                   end
+                 end
+    end
 
-  def document_self=(document_self)
-    return unless @track_visibility
-    return if @done_documenting
+    ##
+    # Should this CodeObject be displayed in output?
+    #
+    # A code object should be displayed if:
+    #
+    # * The item didn't have a nodoc or wasn't in a container that had nodoc
+    # * The item wasn't ignored
+    # * The item has documentation and was not suppressed
+
+    def display?
+      @document_self and not @ignored and
+        (documented? or not @suppressed)
+    end
 
-    @document_self = document_self
-    @received_nodoc = true if document_self.nil?
-  end
+    ##
+    # Enables or disables documentation of this CodeObject's children unless it
+    # has been turned off by :enddoc:
 
-  ##
-  # Does this object have a comment with content or is #received_nodoc true?
+    def document_children=(document_children)
+      return unless @track_visibility
 
-  def documented?
-    @received_nodoc or !@comment.empty?
-  end
+      @document_children = document_children unless @done_documenting
+    end
 
-  ##
-  # Turns documentation on/off, and turns on/off #document_self
-  # and #document_children.
-  #
-  # Once documentation has been turned off (by +:enddoc:+),
-  # the object will refuse to turn #document_self or
-  # #document_children on, so +:doc:+ and +:start_doc:+ directives
-  # will have no effect in the current file.
-
-  def done_documenting=(value)
-    return unless @track_visibility
-    @done_documenting  = value
-    @document_self     = !value
-    @document_children = @document_self
-  end
+    ##
+    # Enables or disables documentation of this CodeObject unless it has been
+    # turned off by :enddoc:.  If the argument is +nil+ it means the
+    # documentation is turned off by +:nodoc:+.
 
-  ##
-  # File name where this CodeObject was found.
-  #
-  # See also RDoc::Context#in_files
+    def document_self=(document_self)
+      return unless @track_visibility
+      return if @done_documenting
 
-  def file_name
-    return unless @file
+      @document_self = document_self
+      @received_nodoc = true if document_self.nil?
+    end
 
-    @file.absolute_name
-  end
+    ##
+    # Does this object have a comment with content or is #received_nodoc true?
 
-  ##
-  # Force the documentation of this object unless documentation
-  # has been turned off by :enddoc:
-  #--
-  # HACK untested, was assigning to an ivar
+    def documented?
+      @received_nodoc or !@comment.empty?
+    end
 
-  def force_documentation=(value)
-    @force_documentation = value unless @done_documenting
-  end
+    ##
+    # Turns documentation on/off, and turns on/off #document_self
+    # and #document_children.
+    #
+    # Once documentation has been turned off (by +:enddoc:+),
+    # the object will refuse to turn #document_self or
+    # #document_children on, so +:doc:+ and +:start_doc:+ directives
+    # will have no effect in the current file.
+
+    def done_documenting=(value)
+      return unless @track_visibility
+      @done_documenting  = value
+      @document_self     = !value
+      @document_children = @document_self
+    end
 
-  ##
-  # Sets the full_name overriding any computed full name.
-  #
-  # Set to +nil+ to clear RDoc's cached value
+    ##
+    # File name where this CodeObject was found.
+    #
+    # See also RDoc::Context#in_files
 
-  def full_name=(full_name)
-    @full_name = full_name
-  end
+    def file_name
+      return unless @file
 
-  ##
-  # Use this to ignore a CodeObject and all its children until found again
-  # (#record_location is called).  An ignored item will not be displayed in
-  # documentation.
-  #
-  # See github issue #55
-  #
-  # The ignored status is temporary in order to allow implementation details
-  # to be hidden.  At the end of processing a file RDoc allows all classes
-  # and modules to add new documentation to previously created classes.
-  #
-  # If a class was ignored (via stopdoc) then reopened later with additional
-  # documentation it should be displayed.  If a class was ignored and never
-  # reopened it should not be displayed.  The ignore flag allows this to
-  # occur.
+      @file.absolute_name
+    end
 
-  def ignore
-    return unless @track_visibility
+    ##
+    # Force the documentation of this object unless documentation
+    # has been turned off by :enddoc:
+    #--
+    # HACK untested, was assigning to an ivar
 
-    @ignored = true
+    def force_documentation=(value)
+      @force_documentation = value unless @done_documenting
+    end
 
-    stop_doc
-  end
+    ##
+    # Sets the full_name overriding any computed full name.
+    #
+    # Set to +nil+ to clear RDoc's cached value
 
-  ##
-  # Has this class been ignored?
-  #
-  # See also #ignore
+    def full_name=(full_name)
+      @full_name = full_name
+    end
 
-  def ignored?
-    @ignored
-  end
+    ##
+    # Use this to ignore a CodeObject and all its children until found again
+    # (#record_location is called).  An ignored item will not be displayed in
+    # documentation.
+    #
+    # See github issue #55
+    #
+    # The ignored status is temporary in order to allow implementation details
+    # to be hidden.  At the end of processing a file RDoc allows all classes
+    # and modules to add new documentation to previously created classes.
+    #
+    # If a class was ignored (via stopdoc) then reopened later with additional
+    # documentation it should be displayed.  If a class was ignored and never
+    # reopened it should not be displayed.  The ignore flag allows this to
+    # occur.
+
+    def ignore
+      return unless @track_visibility
+
+      @ignored = true
+
+      stop_doc
+    end
 
-  ##
-  # The options instance from the store this CodeObject is attached to, or a
-  # default options instance if the CodeObject is not attached.
-  #
-  # This is used by Text#snippet
+    ##
+    # Has this class been ignored?
+    #
+    # See also #ignore
 
-  def options
-    @store&.options || RDoc::Options.new
-  end
+    def ignored?
+      @ignored
+    end
 
-  ##
-  # Our parent CodeObject.  The parent may be missing for classes loaded from
-  # legacy RI data stores.
+    ##
+    # The options instance from the store this CodeObject is attached to, or a
+    # default options instance if the CodeObject is not attached.
+    #
+    # Used by: store= (visibility check), ClassModule#path, TopLevel#path,
+    #          ClassModule#embed_mixins
 
-  def parent
-    return @parent if @parent
-    return nil unless @parent_name
+    def options
+      @store&.options || Options.new
+    end
 
-    if @parent_class == RDoc::TopLevel then
-      @parent = @store.add_file @parent_name
-    else
-      @parent = @store.find_class_or_module @parent_name
+    ##
+    # Our parent CodeObject.  The parent may be missing for classes loaded from
+    # legacy RI data stores.
 
+    def parent
       return @parent if @parent
+      return nil unless @parent_name
+
+      if @parent_class == TopLevel
+        @parent = @store.add_file @parent_name
+      else
+        @parent = @store.find_class_or_module @parent_name
 
-      begin
-        @parent = @store.load_class @parent_name
-      rescue RDoc::Store::MissingFileError
-        nil
+        return @parent if @parent
+
+        begin
+          @parent = @store.load_class @parent_name
+        rescue Store::MissingFileError
+          nil
+        end
       end
     end
-  end
 
-  ##
-  # Name of our parent
+    ##
+    # Name of our parent
 
-  def parent_name
-    @parent ? @parent.full_name : '(unknown)'
-  end
+    def parent_name
+      @parent ? @parent.full_name : '(unknown)'
+    end
 
-  ##
-  # Records the RDoc::TopLevel (file) where this code object was defined
+    ##
+    # Records the RDoc::TopLevel (file) where this code object was defined
 
-  def record_location(top_level)
-    @ignored    = false
-    @suppressed = false
-    @file       = top_level
-  end
+    def record_location(top_level)
+      @ignored    = false
+      @suppressed = false
+      @file       = top_level
+    end
 
-  ##
-  # The section this CodeObject is in.  Sections allow grouping of constants,
-  # attributes and methods inside a class or module.
+    ##
+    # The section this CodeObject is in.  Sections allow grouping of constants,
+    # attributes and methods inside a class or module.
 
-  def section
-    return @section if @section
+    def section
+      return @section if @section
 
-    @section = parent.add_section @section_title if parent
-  end
+      @section = parent.add_section @section_title if parent
+    end
 
-  ##
-  # Enable capture of documentation unless documentation has been
-  # turned off by :enddoc:
+    ##
+    # Enable capture of documentation unless documentation has been
+    # turned off by :enddoc:
 
-  def start_doc
-    return if @done_documenting
+    def start_doc
+      return if @done_documenting
 
-    @document_self = true
-    @document_children = true
-    @ignored    = false
-    @suppressed = false
-  end
+      @document_self = true
+      @document_children = true
+      @ignored    = false
+      @suppressed = false
+    end
 
-  ##
-  # Disable capture of documentation
+    ##
+    # Disable capture of documentation
 
-  def stop_doc
-    return unless @track_visibility
+    def stop_doc
+      return unless @track_visibility
 
-    @document_self = false
-    @document_children = false
-  end
+      @document_self = false
+      @document_children = false
+    end
 
-  ##
-  # Sets the +store+ that contains this CodeObject
+    ##
+    # Sets the +store+ that contains this CodeObject
 
-  def store=(store)
-    @store = store
+    def store=(store)
+      @store = store
 
-    return unless @track_visibility
+      return unless @track_visibility
 
-    if :nodoc == options.visibility then
-      initialize_visibility
-      @track_visibility = false
+      if :nodoc == options.visibility
+        initialize_visibility
+        @track_visibility = false
+      end
     end
-  end
 
-  ##
-  # Use this to suppress a CodeObject and all its children until the next file
-  # it is seen in or documentation is discovered.  A suppressed item with
-  # documentation will be displayed while an ignored item with documentation
-  # may not be displayed.
+    ##
+    # Use this to suppress a CodeObject and all its children until the next file
+    # it is seen in or documentation is discovered.  A suppressed item with
+    # documentation will be displayed while an ignored item with documentation
+    # may not be displayed.
 
-  def suppress
-    return unless @track_visibility
+    def suppress
+      return unless @track_visibility
 
-    @suppressed = true
+      @suppressed = true
 
-    stop_doc
-  end
+      stop_doc
+    end
 
-  ##
-  # Has this class been suppressed?
-  #
-  # See also #suppress
+    ##
+    # Has this class been suppressed?
+    #
+    # See also #suppress
 
-  def suppressed?
-    @suppressed
-  end
+    def suppressed?
+      @suppressed
+    end
 
+  end
 end