Module: RuboCop::Cop::ParamHelp

Included in:
Yardoc::ColumnParams, Yardoc::ParamDocumentation, Yardoc::SupportedTags, Yardoc::TypesFormat, Yardoc::ValidTypes
Defined in:
lib/rubocop/cop/mixin/param_help.rb

Overview

Helper methods to work with node parameters

Defined Under Namespace

Classes: ParameterTag

Instance Method Summary collapse

Instance Method Details

#param_tags_and_positions(node, tags: [:param]) ⇒ Array<ParameterTag>

Extracts "@param" tags and their position in comment block

Parameters:

  • node (RuboCop::AST::Node) —

    The AST node

  • tags (Array<:param, :return>) (defaults to: [:param]) —

    The AST node

Returns:



71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
 
# File 'lib/rubocop/cop/mixin/param_help.rb', line 71

def param_tags_and_positions(node, tags: [:param]) # rubocop:disable Metrics/MethodLength, Metrics/AbcSize, Metrics/CyclomaticComplexity, Metrics/PerceivedComplexity
  comments = node_comments(node)
  tags.map!(&:to_s)

  # Try to match extracted yard tags and source comments
  yard_tags(node)
    .select { |t| tags.include? t.tag_name }
    .map do |yard_tag|
      source_comment = case yard_tag.tag_name
                       when 'param'
                         comments.find { |comment| comment.text.match?(/^# @param\s+#{yard_tag.name}/) }
                       when 'return'
                         comments.find { |comment| comment.text.match?(/^# @return\s+/) }
                       else
                         next
                       end
      description_lines = yard_tag.text ? yard_tag.text.split("\n") : []

      types = yard_tag.types || []
      # Build the regexp with types matched by YARD so we don't have to bother with invalid brackets
      types_s = source_comment.text.match(/\[(#{types.map { |t| Regexp.escape t }.join(',\\s*')})\]/)
      types_s = types_s ? types_s[1] : ''

      desc_pos = description_lines.any? ? source_comment.text.index(description_lines.first) : nil

      ParameterTag.new name:              yard_tag.name,
                       tag_source_line:   source_comment,
                       types:             types,
                       types_s:           types_s,
                       tag_range:         start_tag_position(source_comment, yard_tag.tag_name),
                       type_range:        start_type_position(source_comment, types_s),
                       description_lines: description_lines,
                       type_pos:          source_comment.text.index("[#{types_s}"),
                       desc_pos:          desc_pos
    end
end

#start_tag_position(comment_line, tag_name) ⇒ Parser::Source::Range

Returns the location of "@<tag_name>" of the comment_line in the source buffer

Parameters:

  • comment_line (Parser::Source::Comment) —

    Comment line

  • tag_name (String) —

    Name of the tag

Returns:

  • (Parser::Source::Range) 


38
39
40
41
42
43
44
45
 
# File 'lib/rubocop/cop/mixin/param_help.rb', line 38

def start_tag_position(comment_line, tag_name)
  comment_range = comment_line.loc.expression
  at_pos        = comment_line.text.index('@')

  Parser::Source::Range.new processed_source.buffer,
                            comment_range.begin_pos + at_pos,
                            comment_range.begin_pos + at_pos + tag_name.length + 1
end

#start_type_position(comment_line, types) ⇒ Parser::Source::Range?

Returns the location of the whole type definition of the comment_line in the source buffer

Parameters:

  • comment_line (Parser::Source::Comment) —

    Comment line

  • types (String) —

    Actual type string without the brackets

Returns:

  • (Parser::Source::Range, nil) —

    Nil when no range can be found



54
55
56
57
58
59
60
61
62
63
 
# File 'lib/rubocop/cop/mixin/param_help.rb', line 54

def start_type_position(comment_line, types)
  return nil if types.empty?

  comment_range = comment_line.loc.expression
  at_pos        = comment_line.text.index('[')

  Parser::Source::Range.new processed_source.buffer,
                            comment_range.begin_pos + at_pos,
                            comment_range.begin_pos + at_pos + 2 + types.length
end