class RuboCop::Cop::Style::Documentation
This cop checks for missing top-level documentation of classes and modules. Classes with no body are exempt from the check and so are namespace modules - modules that have nothing in their bodies except classes, other modules, or constant definitions.
The documentation requirement is annulled if the class or module has a β#:nodoc:β comment next to it. Likewise, β#:nodoc: allβ does the same for all its children.
@example
# bad class Person # ... end # good # Description/Explanation of Person class class Person # ... end
Constants
- MSG
Public Instance Methods
on_class(node)
click to toggle source
# File lib/rubocop/cop/style/documentation.rb, line 35 def on_class(node) return unless node.body check(node, node.body, :class) end
on_module(node)
click to toggle source
# File lib/rubocop/cop/style/documentation.rb, line 41 def on_module(node) check(node, node.body, :module) end
Private Instance Methods
check(node, body, type)
click to toggle source
# File lib/rubocop/cop/style/documentation.rb, line 47 def check(node, body, type) return if namespace?(body) return if documentation_comment?(node) || nodoc_comment?(node) return if compact_namespace?(node) && nodoc_comment?(outer_module(node).first) add_offense(node, location: :keyword, message: format(MSG, type: type)) end
compact_namespace?(node)
click to toggle source
# File lib/rubocop/cop/style/documentation.rb, line 68 def compact_namespace?(node) node.loc.name.source =~ /::/ end
namespace?(node)
click to toggle source
# File lib/rubocop/cop/style/documentation.rb, line 58 def namespace?(node) return false unless node if node.begin_type? node.children.all? { |child| constant_definition?(child) } else constant_definition?(node) end end
nodoc(node)
click to toggle source
# File lib/rubocop/cop/style/documentation.rb, line 91 def nodoc(node) processed_source.ast_with_comments[node.children.first].first end
nodoc?(comment, require_all = false)
click to toggle source
# File lib/rubocop/cop/style/documentation.rb, line 87 def nodoc?(comment, require_all = false) comment.text =~ /^#\s*:nodoc:#{"\s+all\s*$" if require_all}/ end
nodoc_comment?(node, require_all = false)
click to toggle source
First checks if the :nodoc: comment is associated with the class/module. Unless the element is tagged with :nodoc:, the search proceeds to check its ancestors for :nodoc: all. Note: How end-of-line comments are associated with code changed in parser-2.2.0.4.
# File lib/rubocop/cop/style/documentation.rb, line 77 def nodoc_comment?(node, require_all = false) return false unless node&.children&.first nodoc = nodoc(node) return true if same_line?(nodoc, node) && nodoc?(nodoc, require_all) nodoc_comment?(node.parent, true) end