Class: RubyLint::Docstring::Parser

Inherits:
Object
  • Object
show all
Defined in:
lib/ruby-lint/docstring/parser.rb

Overview

Parser parses a collection of Ruby source comments and tries to extract various YARD tags out of them. These tags can then be used as extra information for building definitions (e.g. the arguments of a method definition).

Constant Summary

COMMENT_REGEXP =

Regexp used to get rid of leading # markers. This makes the regular expressions used for tags a little bit easier.

Returns:

  • (Regexp) 
/^#+\s*/
TYPE_SEPARATOR =

The character used for separating types in a tag.

Returns:

'|'
KNOWN_TAGS =

Hash containing regular expressions and their corresponding callback methods.

Returns:

  • (Hash) 
{
  # Matches: @param [Type] name description
  # Matches: @param [Type<Value>] name description
  /^@param\s+\[(.+)\]\s+(\S+)\s*(.+)*/ => :on_param_with_type,

  # Matches: @param name description
  /^@param\s+(\S+)\s*(.+)*/ => :on_param,

  # Matches: @return [Type] description
  /^@return\s+\[(.+)\]\s*(.+)*/ => :on_return_with_type,

  # Matches; @return description
  /^@return\s+(.+)/ => :on_return,
}

Instance Method Summary collapse

Instance Method Details

#on_param(name, description) ⇒ RubyLint::Docstring::ParamTag (private)

Processes a @param tag without a given type.

Parameters:

  • name (String) —

    The name of the argument.

  • description (String) —

    The description of the argument.

Returns:



84
85
86
 
# File 'lib/ruby-lint/docstring/parser.rb', line 84

def on_param(name, description)
  return ParamTag.new(:name => name, :description => description)
end

#on_param_with_type(types, name, description) ⇒ Object (private)

Processes a @param tag with a set of types specified.

Parameters:

  • types (String) —

    The argument types.

See Also:



94
95
96
97
98
99
100
101
102
103
104
105
106
 
# File 'lib/ruby-lint/docstring/parser.rb', line 94

def on_param_with_type(types, name, description)
  # The inner values of compound types are ignored since ruby-lint
  # doesn't have the means to store this information.
  types = types.split(TYPE_SEPARATOR).map do |type|
    type.gsub(/<.+>/, '')
  end

  return ParamTag.new(
    :name        => name,
    :description => description,
    :types       => types
  )
end

#on_return(description) ⇒ RubyLint::Docstring::ReturnTag (private)

Processes a @return tag with just the description.

Parameters:

Returns:



114
115
116
 
# File 'lib/ruby-lint/docstring/parser.rb', line 114

def on_return(description)
  return ReturnTag.new(:description => description)
end

#on_return_with_type(types, description) ⇒ RubyLint::Docstring::ReturnTag (private)

Processes a @return tag with the type and description.

Parameters:

Returns:



125
126
127
128
129
130
 
# File 'lib/ruby-lint/docstring/parser.rb', line 125

def on_return_with_type(types, description)
  return ReturnTag.new(
    :description => description,
    :types       => types.split(TYPE_SEPARATOR)
  )
end

#parse(comments) ⇒ Array

Parses an Array of comments and returns a collection of docstring tags.

Parameters:

  • comments (Array)

Returns:

  • (Array) 


52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
 
# File 'lib/ruby-lint/docstring/parser.rb', line 52

def parse(comments)
  tags = []

  comments.each do |comment|
    comment = comment.gsub(COMMENT_REGEXP, '').strip

    KNOWN_TAGS.each do |regexp, method|
      matchdata = comment.match(regexp)

      if matchdata
        retval = send(method, *matchdata.captures)

        if retval
          tags << retval
          break
        end
      end
    end
  end

  return tags
end