Module: Ruby::Merge::DocCommentSupport

Defined in:
lib/ruby/merge/doc_comment_support.rb

Overview

Ruby-specific doc-comment semantics shared by Ruby parser providers.

Constant Summary collapse

TAG_PREFIX = 
/\A@[a-z_]+\b/
EXAMPLE_TAG = 
/\A@example\b(?<rest>.*)\z/
MAGIC_COMMENT_PREFIXES = 
%w[
  coding
  encoding
  frozen_string_literal
  shareable_constant_value
  typed
  warn_indent
].freeze

Class Method Summary collapse

Class Method Details

.comment_prefix_for(raw) ⇒ Object 



24
25
26
 
# File 'lib/ruby/merge/doc_comment_support.rb', line 24

def comment_prefix_for(raw)
  raw.to_s[/\A\s*#\s*/] || '# '
end

.declared_example_language(rest) ⇒ Object 



41
42
43
44
 
# File 'lib/ruby/merge/doc_comment_support.rb', line 41

def declared_example_language(rest)
  match = rest.to_s.strip.match(/\A\[(?<language>[^\]]+)\]/)
  normalize_language(match && match[:language])
end

.declared_example_language_for_tag(content) ⇒ Object 



46
47
48
49
50
51
 
# File 'lib/ruby/merge/doc_comment_support.rb', line 46

def declared_example_language_for_tag(content)
  match = EXAMPLE_TAG.match(content.to_s)
  return unless match

  declared_example_language(match[:rest])
end

.doc_comment_content?(raw, magic_comment: false) ⇒ Boolean

Returns:

  • (Boolean) 


28
29
30
31
32
33
34
35
 
# File 'lib/ruby/merge/doc_comment_support.rb', line 28

def doc_comment_content?(raw, magic_comment: false)
  content = normalize_comment_content(raw)
  return false if content.empty?
  return false if BlockDirectiveDetector.directive_content?(content)
  return false if magic_comment || magic_comment_content?(content)

  true
end

.example_blocks(entries) ⇒ Object 



71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
 
# File 'lib/ruby/merge/doc_comment_support.rb', line 71

def example_blocks(entries)
  normalized = entries.map { |entry| normalize_comment_content(entry[:raw]) }
  normalized.each_with_index.filter_map do |content, tag_index|
    match = EXAMPLE_TAG.match(content)
    next unless match

    body_start_index = tag_index + 1
    body_end_index = next_tag_index(normalized, body_start_index) || normalized.length
    next if body_start_index >= body_end_index

    body_entries = entries[body_start_index...body_end_index]
    next if body_entries.nil? || body_entries.empty?

    {
      tag_index: tag_index,
      tag_line: entries[tag_index][:line],
      tag_text: normalized[tag_index],
      body_start_index: body_start_index,
      body_end_index: body_end_index,
      body_entries: body_entries,
      declared_language: declared_example_language(match[:rest])
    }
  end
end

.magic_comment_content?(content) ⇒ Boolean

Returns:

  • (Boolean) 


37
38
39
 
# File 'lib/ruby/merge/doc_comment_support.rb', line 37

def magic_comment_content?(content)
  MAGIC_COMMENT_PREFIXES.any? { |prefix| content.to_s.start_with?("#{prefix}:") }
end

.next_tag_index(normalized_lines, start_index) ⇒ Object 



62
63
64
65
66
67
68
69
 
# File 'lib/ruby/merge/doc_comment_support.rb', line 62

def next_tag_index(normalized_lines, start_index)
  normalized_lines.each_with_index do |content, index|
    next if index < start_index

    return index if TAG_PREFIX.match?(content)
  end
  nil
end

.normalize_comment_content(raw) ⇒ Object 



20
21
22
 
# File 'lib/ruby/merge/doc_comment_support.rb', line 20

def normalize_comment_content(raw)
  raw.to_s.sub(/\A\s*#\s?/, '').strip
end

.normalize_language(language) ⇒ Object 



53
54
55
56
57
58
59
60
 
# File 'lib/ruby/merge/doc_comment_support.rb', line 53

def normalize_language(language)
  return if language.nil?

  normalized = language.to_s.strip.downcase.tr('-', '_')
  return if normalized.empty?

  normalized
end