Class: RuboCop::Cop::Yardoc::YieldDocumentation

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

Overview

Ensures methods that yield a block document it with @yield.

Also checks for @yieldparam when the yield passes arguments, and @yieldreturn when the yield's return value is used.

Examples:

RequireParamDocumentation: true (default)

# bad
def each
  yield item
end

# good
# @yield [item] iterates over items
# @yieldparam item [Object] the current item
def each
  yield item
end

RequireParamDocumentation: false

# bad (no yield documentation)
def each
  yield item
end

# good (ignored missing param documentation)
# @yield [item] iterates over items
def each
  yield item
end

Constant Summary collapse

MSG_YIELD = 
'Method yields a block but is missing a @yield tag.'
MSG_YIELDPARAM = 
'Method yields with arguments but is missing @yieldparam tags.'

Instance Method Summary collapse

Instance Method Details

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

Executed for every method definition

Parameters:

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

    The AST node



44
45
46
47
48
49
50
51
52
53
54
55
56
 
# File 'lib/rubocop/cop/yardoc/yield_documentation.rb', line 44

def on_def(node)
  return unless yields?(node)
  return unless documented?(node)

  tags = yard_tags(node)

  unless tags.any? { |t| t.tag_name == 'yield' }
    add_offense(node, message: MSG_YIELD)
    return
  end

  check_yieldparams(node, tags) if require_param_documentation?
end