deg-yard 0.8.7.1

data/lib/yard/docstring.rb

@@ -0,0 +1,362 @@
+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<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_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 @summary
+      stripped = self.gsub(/<.+?>/m, '').gsub(/[\r\n](?![\r\n])/, ' ').strip
+      open_parens = ['{', '(', '[']
+      close_parens = ['}', ')', ']']
+      num_parens = 0
+      idx = length.times do |index|
+        case stripped[index, 1]
+        when ".", "\r", "\n"
+          next_char = stripped[index + 1, 1].to_s
+          if num_parens == 0 && next_char =~ /^\s*$/
+            break 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 {|t| t.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 {|l| l.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 @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 }
+      list.map {|t| t.tags }.flatten
+    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

data/lib/yard/docstring_parser.rb

@@ -0,0 +1,321 @@
+require 'ostruct'
+
+module YARD
+  # Parses text and creates a {Docstring} object to represent documentation
+  # for a {CodeObjects::Base}. To create a new docstring, you should initialize
+  # the parser and call {#parse} followed by {#to_docstring}.
+  #
+  # == Subclassing Notes
+  #
+  # The DocstringParser can be subclassed and subtituted during parsing by
+  # setting the {Docstring.default_parser} attribute with the name of the
+  # subclass. This allows developers to change the way docstrings are
+  # parsed, allowing for completely different docstring syntaxes.
+  #
+  # @example Creating a Docstring with a DocstringParser
+  #   DocstringParser.new.parse("text here").to_docstring
+  # @example Creating a Custom DocstringParser
+  #   # Parses docstrings backwards!
+  #   class ReverseDocstringParser
+  #     def parse_content(content)
+  #       super(content.reverse)
+  #     end
+  #   end
+  #
+  #   # Set the parser as default when parsing
+  #   YARD::Docstring.default_parser = ReverseDocstringParser
+  # @see #parse_content
+  # @since 0.8.0
+  class DocstringParser
+    # @return [String] the parsed text portion of the docstring,
+    #   with tags removed.
+    attr_accessor :text
+
+    # @return [String] the complete input string to the parser.
+    attr_accessor :raw_text
+
+    # @return [Array<Tag>] the list of meta-data tags identified
+    #   by the parser
+    attr_accessor :tags
+
+    # @return [Array<Directive>] a list of directives identified
+    #   by the parser. This list will not be passed on to the
+    #   Docstring object.
+    attr_accessor :directives
+
+    # @return [OpenStruct] any arbitrary state to be passed between
+    #   tags during parsing. Mainly used by directives to coordinate
+    #   behaviour (so that directives can be aware of other directives
+    #   used in a docstring).
+    attr_accessor :state
+
+    # @return [CodeObjects::Base, nil] the object associated with
+    #   the docstring being parsed. May be nil if the docstring is
+    #   not attached to any object.
+    attr_accessor :object
+
+    # @return [CodeObjects::Base, nil] the object referenced by
+    #   the docstring being parsed. May be nil if the docstring doesn't
+    #   refer to any object.
+    attr_accessor :reference
+
+    # @return [Handlers::Base, nil] the handler parsing this
+    #   docstring. May be nil if this docstring parser is not
+    #   initialized through
+    attr_accessor :handler
+
+    # @return [Tags::Library] the tag library being used to
+    #   identify registered tags in the docstring.
+    attr_accessor :library
+
+    # The regular expression to match the tag syntax
+    META_MATCH = /^@(!)?((?:\w\.?)+)(?:\s+(.*))?$/i
+
+    # @!group Creation and Conversion Methods
+
+    # Creates a new parser to parse docstring data
+    #
+    # @param [Tags::Library] library a tag library for recognizing
+    #   tags.
+    def initialize(library = Tags::Library.instance)
+      @text = ""
+      @raw_text = ""
+      @tags = []
+      @directives = []
+      @library = library
+      @object = nil
+      @reference = nil
+      @handler = nil
+      @state = OpenStruct.new
+    end
+
+    # @return [Docstring] translates parsed text into
+    #   a Docstring object.
+    def to_docstring
+      Docstring.new!(text, tags, object, raw_text, reference)
+    end
+
+    # @!group Parsing Methods
+
+    # Parses all content and returns itself.
+    #
+    # @param [String] content the docstring text to parse
+    # @param [CodeObjects::Base] object the object that the docstring
+    #   is attached to. Will be passed to directives to act on
+    #   this object.
+    # @param [Handlers::Base, nil] handler the handler object that is
+    #   parsing this object. May be nil if this parser is not being
+    #   called from a {Parser::SourceParser} context.
+    # @return [self] the parser object. To get the docstring,
+    #   call {#to_docstring}.
+    # @see #to_docstring
+    def parse(content, object = nil, handler = nil)
+      @object = object
+      @handler = handler
+      @reference, @raw_text = detect_reference(content)
+      text = parse_content(@raw_text)
+      # Remove trailing/leading whitespace / newlines
+      @text = text.gsub(/\A[\r\n\s]+|[\r\n\s]+\Z/, '')
+      call_directives_after_parse
+      call_after_parse_callbacks
+      self
+    end
+
+    # Parses a given block of text.
+    #
+    # @param [String] content the content to parse
+    # @note Subclasses can override this method to perform custom
+    #   parsing of content data.
+    def parse_content(content)
+      content = content.split(/\r?\n/) if content.is_a?(String)
+      return '' if !content || content.empty?
+      docstring = ""
+
+      indent, last_indent = content.first[/^\s*/].length, 0
+      orig_indent = 0
+      directive = false
+      last_line = ""
+      tag_name, tag_klass, tag_buf = nil, nil, []
+
+      (content+['']).each_with_index do |line, index|
+        indent = line[/^\s*/].length
+        empty = (line =~ /^\s*$/ ? true : false)
+        done = content.size == index
+
+        if tag_name && (((indent < orig_indent && !empty) || done ||
+            (indent == 0 && !empty)) || (indent <= last_indent && line =~ META_MATCH))
+          buf = tag_buf.join("\n")
+          if directive || tag_is_directive?(tag_name)
+            directive = create_directive(tag_name, buf)
+            if directive
+              docstring << parse_content(directive.expanded_text).chomp
+            end
+          else
+            create_tag(tag_name, buf)
+          end
+          tag_name, tag_buf, directive = nil, [], false
+          orig_indent = 0
+        end
+
+        # Found a meta tag
+        if line =~ META_MATCH
+          directive, tag_name, tag_buf = $1, $2, [($3 || '')]
+        elsif tag_name && indent >= orig_indent && !empty
+          orig_indent = indent if orig_indent == 0
+          # Extra data added to the tag on the next line
+          last_empty = last_line =~ /^[ \t]*$/ ? true : false
+
+          tag_buf << '' if last_empty
+          tag_buf << line.gsub(/^[ \t]{#{orig_indent}}/, '')
+        elsif !tag_name
+          # Regular docstring text
+          docstring << line << "\n"
+        end
+
+        last_indent = indent
+        last_line = line
+      end
+
+      docstring
+    end
+
+    # @!group Tag Manipulation Methods
+
+    # Creates a tag from the {Tags::DefaultFactory tag factory}.
+    #
+    # To add an already created tag object, append it to {#tags}.
+    #
+    # @param [String] tag_name the tag name
+    # @param [String] tag_buf the text attached to the tag with newlines removed.
+    # @return [Tags::Tag, Tags::RefTag] a tag
+    def create_tag(tag_name, tag_buf = '')
+      if tag_buf =~ /\A\s*(?:(\S+)\s+)?\(\s*see\s+(\S+)\s*\)\s*\Z/
+        return create_ref_tag(tag_name, $1, $2)
+      end
+
+      if library.has_tag?(tag_name)
+        @tags += [library.tag_create(tag_name, tag_buf)].flatten
+      else
+        log.warn "Unknown tag @#{tag_name}" +
+          (object ? " in file `#{object.file}` near line #{object.line}" : "")
+      end
+    rescue Tags::TagFormatError
+      log.warn "Invalid tag format for @#{tag_name}" +
+        (object ? " in file `#{object.file}` near line #{object.line}" : "")
+    end
+
+    # Creates a {Tags::RefTag}
+    def create_ref_tag(tag_name, name, object_name)
+      @tags << Tags::RefTagList.new(tag_name, P(object, object_name), name)
+    end
+
+    # Creates a new directive using the registered {#library}
+    # @return [Directive] the directive object that is created
+    def create_directive(tag_name, tag_buf)
+      if library.has_directive?(tag_name)
+        dir = library.directive_create(tag_name, tag_buf, self)
+        if dir.is_a?(Tags::Directive)
+          @directives << dir
+          dir
+        end
+      else
+        log.warn "Unknown directive @!#{tag_name}" +
+          (object ? " in file `#{object.file}` near line #{object.line}" : "")
+        nil
+      end
+    rescue Tags::TagFormatError
+      log.warn "Invalid directive format for @!#{tag_name}" +
+        (object ? " in file `#{object.file}` near line #{object.line}" : "")
+      nil
+    end
+
+    # Backward compatibility to detect old tags that should be specified
+    # as directives in 0.8 and onward.
+    def tag_is_directive?(tag_name)
+      list = %w(attribute endgroup group macro method scope visibility)
+      list.include?(tag_name)
+    end
+
+    private
+
+    def namespace
+      if object
+        object.namespace
+      else
+        nil
+      end
+    end
+
+    def detect_reference(content)
+      if content =~ /\A\s*\(see (\S+)\s*\)(?:\s|$)/
+        path, extra = $1, $'
+        [CodeObjects::Proxy.new(namespace, path), extra]
+      else
+        [nil, content]
+      end
+    end
+
+    # @!group Parser Callback Methods
+
+    # Calls the {Directive#after_parse} callback on all the
+    # created directives.
+    def call_directives_after_parse
+      directives.each do |dir|
+        dir.after_parse
+      end
+    end
+
+    # Calls all {after_parse} callbacks
+    def call_after_parse_callbacks
+      self.class.after_parse_callbacks.each do |cb|
+        cb.call(self)
+      end
+    end
+
+    public
+
+    # Creates a callback that is called after a docstring is successfully
+    # parsed. Use this method to perform sanity checks on a docstring's
+    # tag data, or add any extra tags automatically to a docstring.
+    #
+    # @yield [parser] a block to be called after a docstring is parsed
+    # @yieldparam [DocstringParser] parser the docstring parser object
+    #   with all directives and tags created.
+    # @yieldreturn [void]
+    # @return [void]
+    def self.after_parse(&block)
+      self.after_parse_callbacks << block
+    end
+
+    # @return [Array<Proc>] the {after_parse} callback proc objects
+    def self.after_parse_callbacks
+      @after_parse_callbacks ||= []
+    end
+
+    # Define a callback to check that @param tags are properly named
+    after_parse do |parser|
+      next unless parser.object
+      next unless parser.object.is_a?(CodeObjects::MethodObject)
+      next if parser.object.parameters.empty? # method has no params or
+                                                # YARD couldn't detect any.
+                                                # but don't warn user (?)
+      names = parser.object.parameters.map {|l| l.first.gsub(/\W/, '') }
+      seen_names = []
+      infile_info = "\n    in file `#{parser.object.file}' " +
+                    "near line #{parser.object.line}"
+      parser.tags.each do |tag|
+        next if tag.is_a?(Tags::RefTagList) # we don't handle this yet
+        next unless tag.tag_name == "param"
+        if seen_names.include?(tag.name)
+          log.warn "@param tag has duplicate parameter name: " +
+            "#{tag.name} #{infile_info}"
+        elsif names.include?(tag.name)
+          seen_names << tag.name
+        else
+          log.warn "@param tag has unknown parameter name: " +
+            "#{tag.name} #{infile_info}"
+        end
+      end
+    end
+  end
+end

data/lib/yard/globals.rb

@@ -0,0 +1,18 @@
+# @group Global Convenience Methods
+
+# Shortcut for creating a YARD::CodeObjects::Proxy via a path
+#
+# @see YARD::CodeObjects::Proxy
+# @see YARD::Registry.resolve
+def P(namespace, name = nil, type = nil)
+  namespace, name = nil, namespace if name.nil?
+  YARD::Registry.resolve(namespace, name, false, true, type)
+end
+
+# The global {YARD::Logger} instance
+#
+# @return [YARD::Logger] the global {YARD::Logger} instance
+# @see YARD::Logger
+def log
+  YARD::Logger.instance
+end