Class: Yard::Lint::Validators::Documentation::OrphanedDocComment::Validator

Inherits:
Base
  • Object
show all
Defined in:
lib/yard/lint/validators/documentation/orphaned_doc_comment/validator.rb

Overview

Scans source files for YARD-tagged comment blocks that YARD will silently drop. A comment block is orphaned when it has YARD tags but is immediately followed by a non-documentable statement or sits at end-of-file.

Constant Summary collapse

YARD_TAG_PATTERN =

Derive known tag names from YARD’s own registry so we stay in sync with any tags added by YARD plugins. This avoids false positives from instance variable mentions in comments (e.g. ‘# @body.each` or `# @result is nil`).

begin
  tags = ::YARD::Tags::Library.labels.keys.map(&:to_s).sort_by(&:length).reverse.join('|')
  /\A\s*#\s*@(#{tags})\b/
end.freeze
YARD_DIRECTIVE_PATTERN =

Returns matches YARD directive lines (@!macro, @!method, etc.).

Returns:

  • (Regexp) —

    matches YARD directive lines (@!macro, @!method, etc.)

/\A\s*#\s*@!/.freeze
DEFINITION_PATTERN =

Matches method/class/module/attribute/alias definitions (with optional visibility prefix) and constant assignments (uppercase-leading identifier followed by =), both of which YARD tracks and attaches preceding doc comments to. Also matches define_method which YARD handles via a built-in dynamic handler. ‘attrb` is matched after the `attr_*` variants so the bare `attr :name` form (handled by YARD’s attribute handler) is recognised without swallowing them.

/
  \A\s*(private\s+|protected\s+|public\s+)?
  (def |class |module |attr_reader|attr_writer|attr_accessor|attr_internal|attr\b|alias_method\b|alias\b|define_method\b)
  |
  \A\s*[A-Z][A-Za-z0-9_:]*\s*=
/x.freeze
DSL_CALL_PATTERN =

Matches a DSL-style method call whose first argument is a symbol or string literal (e.g. ‘ransacker :foo do`, `validates(:name, …)`, `scope :active, -> { … }`). YARD’s DSL handler turns such a call into a documentable method object when the preceding comment carries an implicit-docstring tag, so a doc comment in front of one of these is NOT orphaned.

/\A\s*(?<method>[a-z_]\w*[!?]?)(?:\s+|\s*\(\s*)(?::\w|:["']|["'])/.freeze
DSL_IGNORE_METHODS =

Mirror of YARD::Handlers::Ruby::DSLHandlerMethods::IGNORE_METHODS - calls to these are skipped by YARD’s DSL handler, so a preceding doc comment really is dropped. (The ‘attr*`/`alias*` entries are already covered by DEFINITION_PATTERN.)

%w[
  alias alias_method autoload attr attr_accessor attr_reader attr_writer
  extend include module_function public private protected private_constant
  private_class_method public_class_method
].freeze
IMPLICIT_DOCSTRING_TAG_PATTERN =

YARD’s DSL handler only creates a method object when the comment carries one of these tags (see DSLHandlerMethods#implicit_docstring?). Matched on raw comment lines because some (‘@method`, `@attribute`, `@scope`, `@visibility`) are not in YARD’s tag registry and would otherwise be missed by YARD_TAG_PATTERN. Directive (‘@!`) forms are excluded here because directive blocks are already skipped upstream.

/\A\s*#\s*@(?:method|attribute|overload|visibility|scope|return)\b/.freeze

Instance Attribute Summary

Attributes inherited from Base

#config, #selection

Instance Method Summary collapse

Methods inherited from Base

in_process, in_process?, in_process_visibility, #initialize, validator_name

Constructor Details

This class inherits a constructor from Yard::Lint::Validators::Base

Instance Method Details

#in_process_query(object, collector) ⇒ void

This method returns an undefined value.

Parameters:

  • object (YARD::CodeObjects::Base) —

    the code object to query

  • collector (Executor::ResultCollector) —

    collector for output



61
62
63
64
65
66
67
68
69
 
# File 'lib/yard/lint/validators/documentation/orphaned_doc_comment/validator.rb', line 61

def in_process_query(object, collector)
  return unless object.file && File.exist?(object.file)

  @scanned_files ||= {}
  return if @scanned_files[object.file]

  @scanned_files[object.file] = true
  scan_file(object.file, collector)
end