diff options
Diffstat (limited to 'lib/rdoc/code_object.rb')
| -rw-r--r-- | lib/rdoc/code_object.rb | 188 |
1 files changed, 151 insertions, 37 deletions
diff --git a/lib/rdoc/code_object.rb b/lib/rdoc/code_object.rb index 54826fffbd..aeb4b4762e 100644 --- a/lib/rdoc/code_object.rb +++ b/lib/rdoc/code_object.rb @@ -1,6 +1,4 @@ -require 'rdoc' -require 'rdoc/text' - +# frozen_string_literal: true ## # Base class for the RDoc code tree. # @@ -23,8 +21,9 @@ require 'rdoc/text' # * RDoc::MetaMethod # * RDoc::Alias # * RDoc::Constant -# * RDoc::Require -# * RDoc::Include +# * RDoc::Mixin +# * RDoc::Require +# * RDoc::Include class RDoc::CodeObject @@ -71,26 +70,24 @@ class RDoc::CodeObject attr_reader :metadata ## - # Offset in #file where this CodeObject was defined - #-- - # TODO character or byte? + # Sets the parent CodeObject - attr_accessor :offset + attr_writer :parent ## - # Our parent CodeObject + # Did we ever receive a +:nodoc:+ directive? - attr_accessor :parent + attr_reader :received_nodoc ## - # Did we ever receive a +:nodoc:+ directive? + # Set the section this CodeObject is in - attr_reader :received_nodoc + attr_writer :section ## - # Which section are we in + # The RDoc::Store for this object. - attr_accessor :section + attr_reader :store ## # We are the model of the code, but we know that at some point we will be @@ -103,18 +100,33 @@ class RDoc::CodeObject # Creates a new CodeObject that will document itself and its children def initialize - @metadata = {} - @comment = '' - @parent = nil - @file = nil - @full_name = nil + @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 + + initialize_visibility + end + ## + # 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 ## @@ -124,16 +136,15 @@ class RDoc::CodeObject @comment = case comment when NilClass then '' when RDoc::Markup::Document then comment + when RDoc::Comment then comment.normalize else if comment and not comment.empty? then normalize_comment comment else - # TODO is this sufficient? # HACK correct fix is to have #initialize create @comment # with the correct encoding - if String === @comment and - Object.const_defined? :Encoding and @comment.empty? then - @comment.force_encoding comment.encoding + if String === @comment and @comment.empty? then + @comment = RDoc::Encoding.change_encoding @comment, comment.encoding end @comment end @@ -141,10 +152,17 @@ class RDoc::CodeObject end ## - # Should this CodeObject be shown in documentation? + # 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 + @document_self and not @ignored and + (documented? or not @suppressed) end ## @@ -152,6 +170,8 @@ class RDoc::CodeObject # has been turned off by :enddoc: def document_children=(document_children) + return unless @track_visibility + @document_children = document_children unless @done_documenting end @@ -161,6 +181,7 @@ class RDoc::CodeObject # documentation is turned off by +:nodoc:+. def document_self=(document_self) + return unless @track_visibility return if @done_documenting @document_self = document_self @@ -184,8 +205,9 @@ class RDoc::CodeObject # will have no effect in the current file. def done_documenting=(value) - @done_documenting = value - @document_self = !value + return unless @track_visibility + @done_documenting = value + @document_self = !value @document_children = @document_self end @@ -216,7 +238,7 @@ class RDoc::CodeObject ## # Force the documentation of this object unless documentation - # has been turned off by :endoc: + # has been turned off by :enddoc: #-- # HACK untested, was assigning to an ivar @@ -235,7 +257,7 @@ class RDoc::CodeObject ## # Use this to ignore a CodeObject and all its children until found again - # (#record_location is called). An ignored item will not be shown in + # (#record_location is called). An ignored item will not be displayed in # documentation. # # See github issue #55 @@ -245,10 +267,13 @@ class RDoc::CodeObject # 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 shown. If a class was ignored and never - # reopened it should not be shown. The ignore flag allows this to occur. + # 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 @@ -256,12 +281,51 @@ class RDoc::CodeObject ## # Has this class been ignored? + # + # See also #ignore def ignored? @ignored 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 + + def options + if @store and @store.rdoc then + @store.rdoc.options + else + RDoc::Options.new + end + end + + ## + # 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 == RDoc::TopLevel then + @parent = @store.add_file @parent_name + else + @parent = @store.find_class_or_module @parent_name + + return @parent if @parent + + begin + @parent = @store.load_class @parent_name + rescue RDoc::Store::MissingFileError + nil + end + end + end + + ## # File name of our parent def parent_file_name @@ -279,29 +343,79 @@ class RDoc::CodeObject # Records the RDoc::TopLevel (file) where this code object was defined def record_location top_level - @ignored = false - @file = 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. + + def section + return @section if @section + + @section = parent.add_section @section_title if parent end ## # Enable capture of documentation unless documentation has been - # turned off by :endoc: + # turned off by :enddoc: def start_doc return if @done_documenting @document_self = true @document_children = true - @ignored = false + @ignored = false + @suppressed = false end ## # Disable capture of documentation def stop_doc + return unless @track_visibility + @document_self = false @document_children = false end -end + ## + # Sets the +store+ that contains this CodeObject + + def store= store + @store = store + + return unless @track_visibility + + if :nodoc == options.visibility then + initialize_visibility + @track_visibility = false + 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. + + def suppress + return unless @track_visibility + + @suppressed = true + + stop_doc + end + + ## + # Has this class been suppressed? + # + # See also #suppress + + def suppressed? + @suppressed + end + +end |