Class: Yard::Lint::Validators::Documentation::DuplicateNamespaceComment::Validator

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

Overview

Flags namespaces (modules and classes) that carry a documentation comment in more than one file. YARD keeps only one docstring per object, so documenting the same reopened namespace in several files silently discards all but one of those comments. Because YARD does not record which reopening carried a comment, the source is re-read at each definition site to detect the documented ones.

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.

Execute query for a single object during in-process execution. Emits one line per namespace documented in two or more files.

Parameters:

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

    the code object to query

  • collector (Executor::ResultCollector) —

    collector for output



37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
 
# File 'lib/yard/lint/validators/documentation/duplicate_namespace_comment/validator.rb', line 37

def in_process_query(object, collector)
  # Only namespaces (modules and classes) get reopened across files.
  # NamespaceObject excludes methods, constants, and the like.
  return unless object.is_a?(YARD::CodeObjects::NamespaceObject)
  # A namespace defined in a single file can only be documented once.
  return if object.files.size < 2

  documented = object.files.select do |file, line|
    line && documented_site?(file, line)
  end

  return if documented.size < 2

  primary_file, primary_line = documented.first
  sites = documented.map { |file, line| "#{file}:#{line}" }.join('|')
  texts = documented.map { |file, line| doc_text(file, line) }
  conflict = texts.uniq.size > 1 ? 'differ' : 'same'

  collector.puts "#{primary_file}:#{primary_line}: #{object.title}\t#{sites}\t#{conflict}"
end