Class: RuboCop::Cop::Yardoc::TagOrder

Inherits:
Base
  • Object
show all
Includes:
RuboCop::Cop::YardHelp
Defined in:
lib/rubocop/cop/yardoc/tag_order.rb

Overview

Ensures YARD tags appear in the configured order.

Override with the Order config option.

Examples:

# bad
# @return [void]
# @param name [String] a name
def foo(name); end

# good
# @param name [String] a name
# @return [void]
def foo(name); end

Order: [return, param]

# bad
# @param name [String] a name
# @return [void]
def foo(name); end

# good
# @return [void]
# @param name [String] a name
def foo(name); end

Constant Summary collapse

MSG = 
'YARD tags are out of order. Expected order: %<order>s. Found `@%<current>s` after `@%<previous>s`.'
DEFAULT_ORDER =

Default expected order corresponding to the "Order" option

%w[param option yieldparam yieldreturn return raise see since deprecated note example].freeze

Instance Method Summary collapse

Instance Method Details

#on_def(node) ⇒ Object Also known as: on_defs, on_module, on_class

Executed for every module/class/method definition (with aliases)

Parameters:

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

    The AST node



42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
 
# File 'lib/rubocop/cop/yardoc/tag_order.rb', line 42

def on_def(node) # rubocop:disable Metrics/AbcSize, Metrics/CyclomaticComplexity,Metrics/MethodLength,Metrics/PerceivedComplexity
  tags = yard_tags(node)
  return if tags.empty?

  tag_names = tags.map(&:tag_name).select { |t| order.include?(t) }

  tag_names.each_cons(2) do |prev_tag, curr_tag|
    prev_idx = order.index(prev_tag)
    curr_idx = order.index(curr_tag)

    # Unknown tags (not in order list) are skipped
    next if prev_idx.nil? || curr_idx.nil?
    next if curr_idx >= prev_idx

    add_offense(
      node,
      message: format(
        MSG,
        order:    order.map { |t| "@#{t}" }.join(', '),
        current:  curr_tag,
        previous: prev_tag
      )
    )

    break
  end
end