yard 0.9.16 → 0.9.17

data/lib/yard/core_ext/symbol_hash.rb

@@ -1,75 +1,75 @@
-# frozen_string_literal: true
-# A subclass of Hash where all keys are converted into Symbols, and
-# optionally, all String values are converted into Symbols.
-class SymbolHash < Hash
-  # Creates a new SymbolHash object
-  #
-  # @param [Boolean] symbolize_value converts any String values into Symbols
-  #   if this is set to +true+.
-  def initialize(symbolize_value = true)
-    @symbolize_value = symbolize_value
-  end
-
-  # @overload [](hash)
-  #   Creates a SymbolHash object from an existing Hash
-  #
-  #   @example
-  #     SymbolHash['x' => 1, :y => 2] # => #<SymbolHash:0x...>
-  #   @param [Hash] hash the hash object
-  #   @return [SymbolHash] a new SymbolHash from a hash object
-  #
-  # @overload [](*list)
-  #   Creates a SymbolHash from an even list of keys and values
-  #
-  #   @example
-  #     SymbolHash[key1, value1, key2, value2, ...]
-  #   @param [Array] list an even list of key followed by value
-  #   @return [SymbolHash] a new SymbolHash object
-  def self.[](*hsh)
-    obj = new
-    if hsh.size == 1 && hsh.first.is_a?(Hash)
-      hsh.first.each {|k, v| obj[k] = v }
-    else
-      0.step(hsh.size, 2) {|n| obj[hsh[n]] = hsh[n + 1] }
-    end
-    obj
-  end
-
-  # Assigns a value to a symbolized key
-  # @param [#to_sym] key the key
-  # @param [Object] value the value to be assigned. If this is a String and
-  #   values are set to be symbolized, it will be converted into a Symbol.
-  def []=(key, value)
-    super(key.to_sym, value.instance_of?(String) && @symbolize_value ? value.to_sym : value)
-  end
-
-  # Accessed a symbolized key
-  # @param [#to_sym] key the key to access
-  # @return [Object] the value associated with the key
-  def [](key) super(key.to_sym) end
-
-  # Deleted a key and value associated with it
-  # @param [#to_sym] key the key to delete
-  # @return [void]
-  def delete(key) super(key.to_sym) end
-
-  # Tests if a symbolized key exists
-  # @param [#to_sym] key the key to test
-  # @return [Boolean] whether the key exists
-  def key?(key) super(key.to_sym) end
-  alias has_key? key?
-
-  # Updates the object with the contents of another Hash object.
-  # This method modifies the original SymbolHash object
-  #
-  # @param [Hash] hash the hash object to copy the values from
-  # @return [SymbolHash] self
-  def update(hash) hash.each {|k, v| self[k] = v }; self end
-  alias merge! update
-
-  # Merges the contents of another hash into a new SymbolHash object
-  #
-  # @param [Hash] hash the hash of objects to copy
-  # @return [SymbolHash] a new SymbolHash containing the merged data
-  def merge(hash) dup.merge!(hash) end
-end
+# frozen_string_literal: true
+# A subclass of Hash where all keys are converted into Symbols, and
+# optionally, all String values are converted into Symbols.
+class SymbolHash < Hash
+  # Creates a new SymbolHash object
+  #
+  # @param [Boolean] symbolize_value converts any String values into Symbols
+  #   if this is set to +true+.
+  def initialize(symbolize_value = true)
+    @symbolize_value = symbolize_value
+  end
+
+  # @overload [](hash)
+  #   Creates a SymbolHash object from an existing Hash
+  #
+  #   @example
+  #     SymbolHash['x' => 1, :y => 2] # => #<SymbolHash:0x...>
+  #   @param [Hash] hash the hash object
+  #   @return [SymbolHash] a new SymbolHash from a hash object
+  #
+  # @overload [](*list)
+  #   Creates a SymbolHash from an even list of keys and values
+  #
+  #   @example
+  #     SymbolHash[key1, value1, key2, value2, ...]
+  #   @param [Array] list an even list of key followed by value
+  #   @return [SymbolHash] a new SymbolHash object
+  def self.[](*hsh)
+    obj = new
+    if hsh.size == 1 && hsh.first.is_a?(Hash)
+      hsh.first.each {|k, v| obj[k] = v }
+    else
+      0.step(hsh.size, 2) {|n| obj[hsh[n]] = hsh[n + 1] }
+    end
+    obj
+  end
+
+  # Assigns a value to a symbolized key
+  # @param [#to_sym] key the key
+  # @param [Object] value the value to be assigned. If this is a String and
+  #   values are set to be symbolized, it will be converted into a Symbol.
+  def []=(key, value)
+    super(key.to_sym, value.instance_of?(String) && @symbolize_value ? value.to_sym : value)
+  end
+
+  # Accessed a symbolized key
+  # @param [#to_sym] key the key to access
+  # @return [Object] the value associated with the key
+  def [](key) super(key.to_sym) end
+
+  # Deleted a key and value associated with it
+  # @param [#to_sym] key the key to delete
+  # @return [void]
+  def delete(key) super(key.to_sym) end
+
+  # Tests if a symbolized key exists
+  # @param [#to_sym] key the key to test
+  # @return [Boolean] whether the key exists
+  def key?(key) super(key.to_sym) end
+  alias has_key? key?
+
+  # Updates the object with the contents of another Hash object.
+  # This method modifies the original SymbolHash object
+  #
+  # @param [Hash] hash the hash object to copy the values from
+  # @return [SymbolHash] self
+  def update(hash) hash.each {|k, v| self[k] = v }; self end
+  alias merge! update
+
+  # Merges the contents of another hash into a new SymbolHash object
+  #
+  # @param [Hash] hash the hash of objects to copy
+  # @return [SymbolHash] a new SymbolHash containing the merged data
+  def merge(hash) dup.merge!(hash) end
+end

data/lib/yard/docstring.rb

@@ -1,378 +1,386 @@
-# frozen_string_literal: true
-module YARD
-  # A documentation string, or "docstring" for short, encapsulates the
-  # comments and metadata, or "tags", of an object. Meta-data is expressed
-  # in the form +@tag VALUE+, where VALUE can span over multiple lines as
-  # long as they are indented. The following +@example+ tag shows how tags
-  # can be indented:
-  #
-  #   # @example My example
-  #   #   a = "hello world"
-  #   #   a.reverse
-  #   # @version 1.0
-  #
-  # Tags can be nested in a documentation string, though the {Tags::Tag}
-  # itself is responsible for parsing the inner tags.
-  class Docstring < String
-    class << self
-      # @note Plugin developers should make sure to reset this value
-      #   after parsing finishes. This can be done via the
-      #   {Parser::SourceParser.after_parse_list} callback. This will
-      #   ensure that YARD can properly parse multiple projects in
-      #   the same process.
-      # @return [Class<DocstringParser>] the parser class used to parse
-      #   text and optional meta-data from docstrings. Defaults to
-      #   {DocstringParser}.
-      # @see DocstringParser
-      # @see Parser::SourceParser.after_parse_list
-      attr_accessor :default_parser
-
-      # Creates a parser object using the current {default_parser}.
-      # Equivalent to:
-      #   Docstring.default_parser.new(*args)
-      # @param args arguments are passed to the {DocstringParser}
-      #   class. See {DocstringParser#initialize} for details on
-      #   arguments.
-      # @return [DocstringParser] the parser object used to parse a
-      #   docstring.
-      def parser(*args) default_parser.new(*args) end
-    end
-
-    self.default_parser = DocstringParser
-
-    # @return [Array<Tags::RefTag>] the list of reference tags
-    attr_reader :ref_tags
-
-    # @return [CodeObjects::Base] the object that owns the docstring.
-    attr_accessor :object
-
-    # @return [Range] line range in the {#object}'s file where the docstring was parsed from
-    attr_accessor :line_range
-
-    # @return [String] the raw documentation (including raw tag text)
-    attr_reader :all
-
-    # @return [Boolean] whether the docstring was started with "##"
-    attr_reader :hash_flag
-    def hash_flag=(v) @hash_flag = v.nil? ? false : v end
-
-    # Matches a tag at the start of a comment line
-    # @deprecated Use {DocstringParser::META_MATCH}
-    META_MATCH = DocstringParser::META_MATCH
-
-    # @group Creating a Docstring Object
-
-    # Creates a new docstring without performing any parsing through
-    # a {DocstringParser}. This method is called by +DocstringParser+
-    # when creating the new docstring object.
-    #
-    # @param [String] text the textual portion of the docstring
-    # @param [Array<Tags::Tag>] tags the list of tag objects in the docstring
-    # @param [CodeObjects::Base, nil] object the object associated with the
-    #   docstring. May be nil.
-    # @param [String] raw_data the complete docstring, including all
-    #   original formatting and any unparsed tags/directives.
-    # @param [CodeObjects::Base, nil] ref_object a reference object used for
-    #   the base set of documentation / tag information.
-    def self.new!(text, tags = [], object = nil, raw_data = nil, ref_object = nil)
-      docstring = allocate
-      docstring.replace(text, false)
-      docstring.object = object
-      docstring.add_tag(*tags)
-      docstring.instance_variable_set("@unresolved_reference", ref_object)
-      docstring.instance_variable_set("@all", raw_data) if raw_data
-      docstring
-    end
-
-    # Creates a new docstring with the raw contents attached to an optional
-    # object. Parsing will be done by the {DocstringParser} class.
-    #
-    # @note To properly parse directives with proper parser context within
-    #   handlers, you should not use this method to create a Docstring.
-    #   Instead, use the {parser}, which takes a handler object that
-    #   can pass parser state onto directives. If a Docstring is created
-    #   with this method, directives do not have access to any parser
-    #   state, and may not function as expected.
-    # @example
-    #   Docstring.new("hello world\n@return Object return", someobj)
-    #
-    # @param [String] content the raw comments to be parsed into a docstring
-    #   and associated meta-data.
-    # @param [CodeObjects::Base] object an object to associate the docstring
-    #   with.
-    def initialize(content = '', object = nil)
-      @object = object
-      @summary = nil
-      @hash_flag = false
-
-      self.all = content
-    end
-
-    # Adds another {Docstring}, copying over tags.
-    #
-    # @param [Docstring, String] other the other docstring (or string) to
-    #   add.
-    # @return [Docstring] a new docstring with both docstrings combines
-    def +(other)
-      case other
-      when Docstring
-        Docstring.new([all, other.all].join("\n"), object)
-      else
-        super
-      end
-    end
-
-    def to_s
-      resolve_reference
-      super
-    end
-
-    # Replaces the docstring with new raw content. Called by {#all=}.
-    # @param [String] content the raw comments to be parsed
-    def replace(content, parse = true)
-      content = content.join("\n") if content.is_a?(Array)
-      @tags = []
-      @ref_tags = []
-      if parse
-        super(parse_comments(content))
-      else
-        @all = content
-        @unresolved_reference = nil
-        super(content)
-      end
-    end
-    alias all= replace
-
-    # Deep-copies a docstring
-    #
-    # @note This method creates a new docstring with new tag lists, but does
-    #   not create new individual tags. Modifying the tag objects will still
-    #   affect the original tags.
-    # @return [Docstring] a new copied docstring
-    # @since 0.7.0
-    def dup
-      resolve_reference
-      obj = super
-      %w(all summary tags ref_tags).each do |name|
-        val = instance_variable_defined?("@#{name}") && instance_variable_get("@#{name}")
-        obj.instance_variable_set("@#{name}", val ? val.dup : nil)
-      end
-      obj
-    end
-
-    # @endgroup
-
-    # @return [Fixnum] the first line of the {#line_range}
-    # @return [nil] if there is no associated {#line_range}
-    def line
-      line_range ? line_range.first : nil
-    end
-
-    # Gets the first line of a docstring to the period or the first paragraph.
-    # @return [String] The first line or paragraph of the docstring; always ends with a period.
-    def summary
-      resolve_reference
-      return @summary if defined?(@summary) && @summary
-      stripped = gsub(/[\r\n](?![\r\n])/, ' ').strip
-      num_parens = 0
-      idx = length.times do |index|
-        case stripped[index, 1]
-        when "."
-          next_char = stripped[index + 1, 1].to_s
-          break index - 1 if num_parens <= 0 && next_char =~ /^\s*$/
-        when "\r", "\n"
-          next_char = stripped[index + 1, 1].to_s
-          if next_char =~ /^\s*$/
-            break stripped[index - 1, 1] == '.' ? index - 2 : index - 1
-          end
-        when "{", "(", "["
-          num_parens += 1
-        when "}", ")", "]"
-          num_parens -= 1
-        end
-      end
-      @summary = stripped[0..idx]
-      if !@summary.empty? && @summary !~ /\A\s*\{include:.+\}\s*\Z/
-        @summary += '.'
-      end
-      @summary
-    end
-
-    # Reformats and returns a raw representation of the tag data using the
-    # current tag and docstring data, not the original text.
-    #
-    # @return [String] the updated raw formatted docstring data
-    # @since 0.7.0
-    # @todo Add Tags::Tag#to_raw and refactor
-    def to_raw
-      tag_data = tags.sort_by(&:tag_name).map do |tag|
-        case tag
-        when Tags::OverloadTag
-          tag_text = "@#{tag.tag_name} #{tag.signature}\n"
-          unless tag.docstring.blank?
-            tag_text += "\n  " + tag.docstring.all.gsub(/\r?\n/, "\n  ")
-          end
-        when Tags::OptionTag
-          tag_text = "@#{tag.tag_name} #{tag.name}"
-          tag_text += ' [' + tag.pair.types.join(', ') + ']' if tag.pair.types
-          tag_text += ' ' + tag.pair.name.to_s if tag.pair.name
-          tag_text += "\n " if tag.name && tag.text
-          tag_text += ' (' + tag.pair.defaults.join(', ') + ')' if tag.pair.defaults
-          tag_text += " " + tag.pair.text.strip.gsub(/\n/, "\n  ") if tag.pair.text
-        else
-          tag_text = '@' + tag.tag_name
-          tag_text += ' [' + tag.types.join(', ') + ']' if tag.types
-          tag_text += ' ' + tag.name.to_s if tag.name
-          tag_text += "\n " if tag.name && tag.text
-          tag_text += ' ' + tag.text.strip.gsub(/\n/, "\n  ") if tag.text
-        end
-        tag_text
-      end
-      [strip, tag_data.join("\n")].reject(&:empty?).compact.join("\n")
-    end
-
-    # @group Creating and Accessing Meta-data
-
-    # Adds a tag or reftag object to the tag list. If you want to parse
-    # tag data based on the {Tags::DefaultFactory} tag factory, use
-    # {DocstringParser} instead.
-    #
-    # @param [Tags::Tag, Tags::RefTag] tags list of tag objects to add
-    # @return [void]
-    def add_tag(*tags)
-      tags.each_with_index do |tag, i|
-        case tag
-        when Tags::Tag
-          tag.object = object
-          @tags << tag
-        when Tags::RefTag, Tags::RefTagList
-          @ref_tags << tag
-        else
-          raise ArgumentError, "expected Tag or RefTag, got #{tag.class} (at index #{i})"
-        end
-      end
-    end
-
-    # Convenience method to return the first tag
-    # object in the list of tag objects of that name
-    #
-    # @example
-    #   doc = Docstring.new("@return zero when nil")
-    #   doc.tag(:return).text  # => "zero when nil"
-    #
-    # @param [#to_s] name the tag name to return data for
-    # @return [Tags::Tag] the first tag in the list of {#tags}
-    def tag(name)
-      tags.find {|tag| tag.tag_name.to_s == name.to_s }
-    end
-
-    # Returns a list of tags specified by +name+ or all tags if +name+ is not specified.
-    #
-    # @param [#to_s] name the tag name to return data for, or nil for all tags
-    # @return [Array<Tags::Tag>] the list of tags by the specified tag name
-    def tags(name = nil)
-      list = @tags + convert_ref_tags
-      return list unless name
-      list.select {|tag| tag.tag_name.to_s == name.to_s }
-    end
-
-    # Returns true if at least one tag by the name +name+ was declared
-    #
-    # @param [String] name the tag name to search for
-    # @return [Boolean] whether or not the tag +name+ was declared
-    def has_tag?(name)
-      tags.any? {|tag| tag.tag_name.to_s == name.to_s }
-    end
-
-    # Delete all tags with +name+
-    # @param [String] name the tag name
-    # @return [void]
-    # @since 0.7.0
-    def delete_tags(name)
-      delete_tag_if {|tag| tag.tag_name.to_s == name.to_s }
-    end
-
-    # Deletes all tags where the block returns true
-    # @yieldparam [Tags::Tag] tag the tag that is being tested
-    # @yieldreturn [Boolean] true if the tag should be deleted
-    # @return [void]
-    # @since 0.7.0
-    def delete_tag_if(&block)
-      @tags.delete_if(&block)
-      @ref_tags.delete_if(&block)
-    end
-
-    # Returns true if the docstring has no content that is visible to a template.
-    #
-    # @param [Boolean] only_visible_tags whether only {Tags::Library.visible_tags}
-    #   should be checked, or if all tags should be considered.
-    # @return [Boolean] whether or not the docstring has content
-    def blank?(only_visible_tags = true)
-      if only_visible_tags
-        empty? && !tags.any? {|tag| Tags::Library.visible_tags.include?(tag.tag_name.to_sym) }
-      else
-        empty? && @tags.empty? && @ref_tags.empty?
-      end
-    end
-
-    # @endgroup
-
-    # Resolves unresolved other docstring reference if there is
-    # unresolved reference. Does nothing if there is no unresolved
-    # reference.
-    #
-    # Normally, you don't need to call this method
-    # explicitly. Resolving unresolved reference is done implicitly.
-    #
-    # @return [void]
-    def resolve_reference
-      loop do
-        return if defined?(@unresolved_reference).nil? || @unresolved_reference.nil?
-        return if CodeObjects::Proxy === @unresolved_reference
-
-        reference = @unresolved_reference
-        @unresolved_reference = nil
-        self.all = [reference.docstring.all, @all].join("\n")
-      end
-    end
-
-    private
-
-    # Maps valid reference tags
-    #
-    # @return [Array<Tags::RefTag>] the list of valid reference tags
-    def convert_ref_tags
-      list = @ref_tags.reject {|t| CodeObjects::Proxy === t.owner }
-
-      @ref_tag_recurse_count ||= 0
-      @ref_tag_recurse_count += 1
-      if @ref_tag_recurse_count > 2
-        log.error "#{@object.file}:#{@object.line}: Detected circular reference tag in " \
-                  "`#{@object}', ignoring all reference tags for this object " \
-                  "(#{@ref_tags.map {|t| "@#{t.tag_name}" }.join(", ")})."
-        @ref_tags = []
-        return @ref_tags
-      end
-      list = list.map(&:tags).flatten
-      @ref_tag_recurse_count -= 1
-      list
-    end
-
-    # Parses out comments split by newlines into a new code object
-    #
-    # @param [String] comments
-    #   the newline delimited array of comments. If the comments
-    #   are passed as a String, they will be split by newlines.
-    #
-    # @return [String] the non-metadata portion of the comments to
-    #   be used as a docstring
-    def parse_comments(comments)
-      parser = self.class.parser
-      parser.parse(comments, object)
-      @all = parser.raw_text
-      @unresolved_reference = parser.reference
-      add_tag(*parser.tags)
-      parser.text
-    end
-  end
-end
+# frozen_string_literal: true
+module YARD
+  # A documentation string, or "docstring" for short, encapsulates the
+  # comments and metadata, or "tags", of an object. Meta-data is expressed
+  # in the form +@tag VALUE+, where VALUE can span over multiple lines as
+  # long as they are indented. The following +@example+ tag shows how tags
+  # can be indented:
+  #
+  #   # @example My example
+  #   #   a = "hello world"
+  #   #   a.reverse
+  #   # @version 1.0
+  #
+  # Tags can be nested in a documentation string, though the {Tags::Tag}
+  # itself is responsible for parsing the inner tags.
+  class Docstring < String
+    class << self
+      # @note Plugin developers should make sure to reset this value
+      #   after parsing finishes. This can be done via the
+      #   {Parser::SourceParser.after_parse_list} callback. This will
+      #   ensure that YARD can properly parse multiple projects in
+      #   the same process.
+      # @return [Class<DocstringParser>] the parser class used to parse
+      #   text and optional meta-data from docstrings. Defaults to
+      #   {DocstringParser}.
+      # @see DocstringParser
+      # @see Parser::SourceParser.after_parse_list
+      attr_accessor :default_parser
+
+      # Creates a parser object using the current {default_parser}.
+      # Equivalent to:
+      #   Docstring.default_parser.new(*args)
+      # @param args arguments are passed to the {DocstringParser}
+      #   class. See {DocstringParser#initialize} for details on
+      #   arguments.
+      # @return [DocstringParser] the parser object used to parse a
+      #   docstring.
+      def parser(*args) default_parser.new(*args) end
+    end
+
+    self.default_parser = DocstringParser
+
+    # @return [Array<Tags::RefTag>] the list of reference tags
+    attr_reader :ref_tags
+
+    # @return [CodeObjects::Base] the object that owns the docstring.
+    attr_accessor :object
+
+    # @return [Range] line range in the {#object}'s file where the docstring was parsed from
+    attr_accessor :line_range
+
+    # @return [String] the raw documentation (including raw tag text)
+    attr_reader :all
+
+    # @return [Boolean] whether the docstring was started with "##"
+    attr_reader :hash_flag
+    def hash_flag=(v) @hash_flag = v.nil? ? false : v end
+
+    # Matches a tag at the start of a comment line
+    # @deprecated Use {DocstringParser::META_MATCH}
+    META_MATCH = DocstringParser::META_MATCH
+
+    # @group Creating a Docstring Object
+
+    # Creates a new docstring without performing any parsing through
+    # a {DocstringParser}. This method is called by +DocstringParser+
+    # when creating the new docstring object.
+    #
+    # @param [String] text the textual portion of the docstring
+    # @param [Array<Tags::Tag>] tags the list of tag objects in the docstring
+    # @param [CodeObjects::Base, nil] object the object associated with the
+    #   docstring. May be nil.
+    # @param [String] raw_data the complete docstring, including all
+    #   original formatting and any unparsed tags/directives.
+    # @param [CodeObjects::Base, nil] ref_object a reference object used for
+    #   the base set of documentation / tag information.
+    def self.new!(text, tags = [], object = nil, raw_data = nil, ref_object = nil)
+      docstring = allocate
+      docstring.replace(text, false)
+      docstring.object = object
+      docstring.add_tag(*tags)
+      docstring.instance_variable_set("@unresolved_reference", ref_object)
+      docstring.instance_variable_set("@all", raw_data) if raw_data
+      docstring
+    end
+
+    # Creates a new docstring with the raw contents attached to an optional
+    # object. Parsing will be done by the {DocstringParser} class.
+    #
+    # @note To properly parse directives with proper parser context within
+    #   handlers, you should not use this method to create a Docstring.
+    #   Instead, use the {parser}, which takes a handler object that
+    #   can pass parser state onto directives. If a Docstring is created
+    #   with this method, directives do not have access to any parser
+    #   state, and may not function as expected.
+    # @example
+    #   Docstring.new("hello world\n@return Object return", someobj)
+    #
+    # @param [String] content the raw comments to be parsed into a docstring
+    #   and associated meta-data.
+    # @param [CodeObjects::Base] object an object to associate the docstring
+    #   with.
+    def initialize(content = '', object = nil)
+      @object = object
+      @summary = nil
+      @hash_flag = false
+
+      self.all = content
+    end
+
+    # Adds another {Docstring}, copying over tags.
+    #
+    # @param [Docstring, String] other the other docstring (or string) to
+    #   add.
+    # @return [Docstring] a new docstring with both docstrings combines
+    def +(other)
+      case other
+      when Docstring
+        Docstring.new([all, other.all].join("\n"), object)
+      else
+        super
+      end
+    end
+
+    def to_s
+      resolve_reference
+      super
+    end
+
+    # Replaces the docstring with new raw content. Called by {#all=}.
+    # @param [String] content the raw comments to be parsed
+    def replace(content, parse = true)
+      content = content.join("\n") if content.is_a?(Array)
+      @tags = []
+      @ref_tags = []
+      if parse
+        super(parse_comments(content))
+      else
+        @all = content
+        @unresolved_reference = nil
+        super(content)
+      end
+    end
+    alias all= replace
+
+    # Deep-copies a docstring
+    #
+    # @note This method creates a new docstring with new tag lists, but does
+    #   not create new individual tags. Modifying the tag objects will still
+    #   affect the original tags.
+    # @return [Docstring] a new copied docstring
+    # @since 0.7.0
+    def dup
+      resolve_reference
+      obj = super
+      %w(all summary tags ref_tags).each do |name|
+        val = instance_variable_defined?("@#{name}") && instance_variable_get("@#{name}")
+        obj.instance_variable_set("@#{name}", val ? val.dup : nil)
+      end
+      obj
+    end
+
+    # @endgroup
+
+    # @return [Fixnum] the first line of the {#line_range}
+    # @return [nil] if there is no associated {#line_range}
+    def line
+      line_range ? line_range.first : nil
+    end
+
+    # Gets the first line of a docstring to the period or the first paragraph.
+    # @return [String] The first line or paragraph of the docstring; always ends with a period.
+    def summary
+      resolve_reference
+      return @summary if defined?(@summary) && @summary
+      stripped = gsub(/[\r\n](?![\r\n])/, ' ').strip
+      num_parens = 0
+      idx = length.times do |index|
+        case stripped[index, 1]
+        when "."
+          next_char = stripped[index + 1, 1].to_s
+          break index - 1 if num_parens <= 0 && next_char =~ /^\s*$/
+        when "\r", "\n"
+          next_char = stripped[index + 1, 1].to_s
+          if next_char =~ /^\s*$/
+            break stripped[index - 1, 1] == '.' ? index - 2 : index - 1
+          end
+        when "{", "(", "["
+          num_parens += 1
+        when "}", ")", "]"
+          num_parens -= 1
+        end
+      end
+      @summary = stripped[0..idx]
+      if !@summary.empty? && @summary !~ /\A\s*\{include:.+\}\s*\Z/
+        @summary += '.'
+      end
+      @summary
+    end
+
+    # Reformats and returns a raw representation of the tag data using the
+    # current tag and docstring data, not the original text.
+    #
+    # @return [String] the updated raw formatted docstring data
+    # @since 0.7.0
+    # @todo Add Tags::Tag#to_raw and refactor
+    def to_raw
+      tag_data = tags.map do |tag|
+        case tag
+        when Tags::OverloadTag
+          tag_text = "@#{tag.tag_name} #{tag.signature}\n"
+          unless tag.docstring.blank?
+            tag_text += "\n  " + tag.docstring.all.gsub(/\r?\n/, "\n  ")
+          end
+        when Tags::OptionTag
+          tag_text = "@#{tag.tag_name} #{tag.name}"
+          tag_text += ' [' + tag.pair.types.join(', ') + ']' if tag.pair.types
+          tag_text += ' ' + tag.pair.name.to_s if tag.pair.name
+          tag_text += "\n " if tag.name && tag.text
+          tag_text += ' (' + tag.pair.defaults.join(', ') + ')' if tag.pair.defaults
+          tag_text += " " + tag.pair.text.strip.gsub(/\n/, "\n  ") if tag.pair.text
+        else
+          tag_text = '@' + tag.tag_name
+          tag_text += ' [' + tag.types.join(', ') + ']' if tag.types
+          tag_text += ' ' + tag.name.to_s if tag.name
+          tag_text += "\n " if tag.name && tag.text
+          tag_text += ' ' + tag.text.strip.gsub(/\n/, "\n  ") if tag.text
+        end
+        tag_text
+      end
+      [strip, tag_data.join("\n")].reject(&:empty?).compact.join("\n")
+    end
+
+    # @group Creating and Accessing Meta-data
+
+    # Adds a tag or reftag object to the tag list. If you want to parse
+    # tag data based on the {Tags::DefaultFactory} tag factory, use
+    # {DocstringParser} instead.
+    #
+    # @param [Tags::Tag, Tags::RefTag] tags list of tag objects to add
+    # @return [void]
+    def add_tag(*tags)
+      tags.each_with_index do |tag, i|
+        case tag
+        when Tags::Tag
+          tag.object = object
+          @tags << tag
+        when Tags::RefTag, Tags::RefTagList
+          @ref_tags << tag
+        else
+          raise ArgumentError, "expected Tag or RefTag, got #{tag.class} (at index #{i})"
+        end
+      end
+    end
+
+    # Convenience method to return the first tag
+    # object in the list of tag objects of that name
+    #
+    # @example
+    #   doc = Docstring.new("@return zero when nil")
+    #   doc.tag(:return).text  # => "zero when nil"
+    #
+    # @param [#to_s] name the tag name to return data for
+    # @return [Tags::Tag] the first tag in the list of {#tags}
+    def tag(name)
+      tags.find {|tag| tag.tag_name.to_s == name.to_s }
+    end
+
+    # Returns a list of tags specified by +name+ or all tags if +name+ is not specified.
+    #
+    # @param [#to_s] name the tag name to return data for, or nil for all tags
+    # @return [Array<Tags::Tag>] the list of tags by the specified tag name
+    def tags(name = nil)
+      list = stable_sort_by(@tags + convert_ref_tags, &:tag_name)
+      return list unless name
+      list.select {|tag| tag.tag_name.to_s == name.to_s }
+    end
+
+    # Returns true if at least one tag by the name +name+ was declared
+    #
+    # @param [String] name the tag name to search for
+    # @return [Boolean] whether or not the tag +name+ was declared
+    def has_tag?(name)
+      tags.any? {|tag| tag.tag_name.to_s == name.to_s }
+    end
+
+    # Delete all tags with +name+
+    # @param [String] name the tag name
+    # @return [void]
+    # @since 0.7.0
+    def delete_tags(name)
+      delete_tag_if {|tag| tag.tag_name.to_s == name.to_s }
+    end
+
+    # Deletes all tags where the block returns true
+    # @yieldparam [Tags::Tag] tag the tag that is being tested
+    # @yieldreturn [Boolean] true if the tag should be deleted
+    # @return [void]
+    # @since 0.7.0
+    def delete_tag_if(&block)
+      @tags.delete_if(&block)
+      @ref_tags.delete_if(&block)
+    end
+
+    # Returns true if the docstring has no content that is visible to a template.
+    #
+    # @param [Boolean] only_visible_tags whether only {Tags::Library.visible_tags}
+    #   should be checked, or if all tags should be considered.
+    # @return [Boolean] whether or not the docstring has content
+    def blank?(only_visible_tags = true)
+      if only_visible_tags
+        empty? && !tags.any? {|tag| Tags::Library.visible_tags.include?(tag.tag_name.to_sym) }
+      else
+        empty? && @tags.empty? && @ref_tags.empty?
+      end
+    end
+
+    # @endgroup
+
+    # Resolves unresolved other docstring reference if there is
+    # unresolved reference. Does nothing if there is no unresolved
+    # reference.
+    #
+    # Normally, you don't need to call this method
+    # explicitly. Resolving unresolved reference is done implicitly.
+    #
+    # @return [void]
+    def resolve_reference
+      loop do
+        return if defined?(@unresolved_reference).nil? || @unresolved_reference.nil?
+        return if CodeObjects::Proxy === @unresolved_reference
+
+        reference = @unresolved_reference
+        @unresolved_reference = nil
+        self.all = [reference.docstring.all, @all].join("\n")
+      end
+    end
+
+    private
+
+    # Maps valid reference tags
+    #
+    # @return [Array<Tags::RefTag>] the list of valid reference tags
+    def convert_ref_tags
+      list = @ref_tags.reject {|t| CodeObjects::Proxy === t.owner }
+
+      @ref_tag_recurse_count ||= 0
+      @ref_tag_recurse_count += 1
+      if @ref_tag_recurse_count > 2
+        log.error "#{@object.file}:#{@object.line}: Detected circular reference tag in " \
+                  "`#{@object}', ignoring all reference tags for this object " \
+                  "(#{@ref_tags.map {|t| "@#{t.tag_name}" }.join(", ")})."
+        @ref_tags = []
+        return @ref_tags
+      end
+      list = list.map(&:tags).flatten
+      @ref_tag_recurse_count -= 1
+      list
+    end
+
+    # Parses out comments split by newlines into a new code object
+    #
+    # @param [String] comments
+    #   the newline delimited array of comments. If the comments
+    #   are passed as a String, they will be split by newlines.
+    #
+    # @return [String] the non-metadata portion of the comments to
+    #   be used as a docstring
+    def parse_comments(comments)
+      parser = self.class.parser
+      parser.parse(comments, object)
+      @all = parser.raw_text
+      @unresolved_reference = parser.reference
+      add_tag(*parser.tags)
+      parser.text
+    end
+
+    # A stable sort_by method.
+    #
+    # @param list [Enumerable] the list to sort.
+    # @return [Array] a stable sorted list.
+    def stable_sort_by(list)
+      list.each_with_index.sort_by {|tag, i| [yield(tag), i] }.map(&:first)
+    end
+  end
+end