Class: Yard::Lint::Validators::Documentation::UnderfilledLines::Validator

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

Overview

Detects documentation prose that wraps before using the available line width.

Uses YARD’s ‘docstring.line_range` to locate the exact source lines belonging to the docstring block (mirroring LineLength), classifies each line as prose or structural, groups contiguous prose into paragraphs, and reports a paragraph when greedily re-wrapping it at `MaxLength` would use fewer lines.

Constant Summary collapse

TRAILING_CLOSERS =

Characters that may trail a sentence boundary char without changing the fact that the line ends a clause (closing bracket/quote/backtick).

/[)\]"'`]+\z/

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.

Parameters:

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

    the code object to query

  • collector (Executor::ResultCollector) —

    collector for output



25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
 
# File 'lib/yard/lint/validators/documentation/underfilled_lines/validator.rb', line 25

def in_process_query(object, collector)
  return unless object.file && File.exist?(object.file)
  return if object.docstring.all.empty?

  line_range = object.docstring.line_range
  return unless line_range
  return if duplicate_docstring?(object)

  max_length = config_or_default('MaxLength').to_i
  min_trailing = config_or_default('MinTrailingSpace').to_i
  min_lines = [config_or_default('MinParagraphLines').to_i, 2].max
  boundary = Array(config_or_default('SentenceEndChars'))
  skip_non_ascii = config_or_default('SkipNonAscii')

  source_lines = cached_lines(object.file)
  classified = classify_lines(line_range, source_lines, skip_non_ascii)

  violations = []
  group_paragraphs(classified).each do |paragraph|
    next if paragraph.size < min_lines
    next if ventilated?(paragraph, boundary)

    actual = paragraph.size
    reflowed = reflow_count(paragraph, max_length)
    next unless reflowed < actual

    widest = paragraph[0..-2].map { |line| line[:length] }.max
    next if (max_length - widest) < min_trailing

    violations << "#{paragraph.first[:line_no]}:#{actual}:#{reflowed}:#{widest}"
  end

  return if violations.empty?

  collector.puts "#{object.file}:#{object.line}: #{object.title}"
  collector.puts "#{max_length}|#{violations.join('|')}"
end