Module: Docscribe::InlineRewriter::DocBlock

Defined in:
lib/docscribe/inline_rewriter/doc_block.rb

Overview

Text-preserving doc-block parsing and tag sorting helpers.

This module operates on existing comment blocks and is used to:

  • preserve user-authored tag text exactly

  • append generated missing tag entries

  • sort only configured sortable tags

  • preserve boundaries such as prose comments and blank comment lines

Defined Under Namespace

Classes: Entry

Class Attribute Summary collapse

Class Method Summary collapse

Class Attribute Details

.generated ⇒ Boolean

Parameters:

  • value (Boolean)

Returns:

  • (Boolean) 


42
43
44
45
46
47
48
49
50
51
 
# File 'lib/docscribe/inline_rewriter/doc_block.rb', line 42

Entry = Struct.new(
  :kind,
  :tag,
  :lines,
  :subject,
  :option_owner,
  :generated,
  :index,
  keyword_init: true
)

.index ⇒ Integer

Parameters:

  • value (Integer)

Returns:

  • (Integer) 


42
43
44
45
46
47
48
49
50
51
 
# File 'lib/docscribe/inline_rewriter/doc_block.rb', line 42

Entry = Struct.new(
  :kind,
  :tag,
  :lines,
  :subject,
  :option_owner,
  :generated,
  :index,
  keyword_init: true
)

.kind ⇒ Symbol

Parameters:

  • value (Symbol)

Returns:

  • (Symbol) 


42
43
44
45
46
47
48
49
50
51
 
# File 'lib/docscribe/inline_rewriter/doc_block.rb', line 42

Entry = Struct.new(
  :kind,
  :tag,
  :lines,
  :subject,
  :option_owner,
  :generated,
  :index,
  keyword_init: true
)

.lines ⇒ Array<String>

Parameters:

  • value (Array<String>)

Returns:

  • (Array<String>) 


42
43
44
45
46
47
48
49
50
51
 
# File 'lib/docscribe/inline_rewriter/doc_block.rb', line 42

Entry = Struct.new(
  :kind,
  :tag,
  :lines,
  :subject,
  :option_owner,
  :generated,
  :index,
  keyword_init: true
)

.option_owner ⇒ String?

Parameters:

  • value (String?)

Returns:

  • (String?) 


42
43
44
45
46
47
48
49
50
51
 
# File 'lib/docscribe/inline_rewriter/doc_block.rb', line 42

Entry = Struct.new(
  :kind,
  :tag,
  :lines,
  :subject,
  :option_owner,
  :generated,
  :index,
  keyword_init: true
)

.subject ⇒ String?

Parameters:

  • value (String?)

Returns:

  • (String?) 


42
43
44
45
46
47
48
49
50
51
 
# File 'lib/docscribe/inline_rewriter/doc_block.rb', line 42

Entry = Struct.new(
  :kind,
  :tag,
  :lines,
  :subject,
  :option_owner,
  :generated,
  :index,
  keyword_init: true
)

.tag ⇒ String

Parameters:

  • value (String)

Returns:

  • (String) 


42
43
44
45
46
47
48
49
50
51
 
# File 'lib/docscribe/inline_rewriter/doc_block.rb', line 42

Entry = Struct.new(
  :kind,
  :tag,
  :lines,
  :subject,
  :option_owner,
  :generated,
  :index,
  keyword_init: true
)

Class Method Details

.add_continuation_lines(lines, start_idx, result, sortable_tags) ⇒ void

Note:

module_function: defines #add_continuation_lines (visibility: private)

This method returns an undefined value.

Append continuation lines to the result array until a non-continuation line is found.

Parameters:

  • lines (Array<String>) —

    comment block lines

  • start_idx (Integer) —

    index to start scanning from

  • result (Array<String>) —

    accumulated entry lines

  • sortable_tags (Array<String>) —

    tag names treated as sortable



389
390
391
392
393
394
395
396
397
398
 
# File 'lib/docscribe/inline_rewriter/doc_block.rb', line 389

def add_continuation_lines(lines, start_idx, result, sortable_tags)
  i = start_idx
  while i < lines.length
    line = lines[i]
    break unless continuation_candidate?(line, sortable_tags)

    result << line
    i += 1
  end
end

.blank_comment_line?(line) ⇒ Boolean

Note:

module_function: defines #blank_comment_line? (visibility: private)

Whether a line is a blank comment separator such as ‘#`.

Parameters:

  • line (String) —

    the line to check

Returns:

  • (Boolean) 


551
552
553
 
# File 'lib/docscribe/inline_rewriter/doc_block.rb', line 551

def blank_comment_line?(line)
  !!(line =~ /^\s*#\s*$/)
end

.build_groups(entries) ⇒ Array<Array<Docscribe::InlineRewriter::DocBlock::Entry>>

Note:

module_function: defines #build_groups (visibility: private)

Group entries so related ‘@option` tags stay attached to their owning `@param`.

Parameters:

Returns:



261
262
263
264
265
 
# File 'lib/docscribe/inline_rewriter/doc_block.rb', line 261

def build_groups(entries)
  groups = [] #: Array[untyped]
  group_entries_loop(entries, groups)
  groups
end

.build_other_entry(line, index) ⇒ Docscribe::InlineRewriter::DocBlock::Entry

Note:

module_function: defines #build_other_entry (visibility: private)

Create an :other entry for a non-tag line (prose, blank separators, etc.).

Parameters:

  • line (String) —

    the comment line

  • index (Integer) —

    stable ordering index

Returns:



178
179
180
 
# File 'lib/docscribe/inline_rewriter/doc_block.rb', line 178

def build_other_entry(line, index)
  Entry.new(kind: :other, lines: [line], generated: false, index: index)
end

.build_param_group(entries, idx, entry) ⇒ Array<Docscribe::InlineRewriter::DocBlock::Entry>

Note:

module_function: defines #build_param_group (visibility: private)

Build a group starting with a @param entry and including its following @option entries.

Parameters:

Returns:



304
305
306
307
308
309
310
311
312
313
314
315
316
317
 
# File 'lib/docscribe/inline_rewriter/doc_block.rb', line 304

def build_param_group(entries, idx, entry)
  group = [entry]
  idx += 1

  while idx < entries.length &&
        entries[idx].tag == 'option' &&
        entries[idx].option_owner &&
        entries[idx].option_owner == entry.subject
    group << entries[idx]
    idx += 1
  end

  group
end

.build_priority(tag_order) ⇒ Hash<String, Integer>

Note:

module_function: defines #build_priority (visibility: private)

Build a tag priority map from configured order.

Parameters:

  • tag_order (Array<String>) —

    configured sortable tag order

Returns:

  • (Hash<String, Integer>) 


334
335
336
 
# File 'lib/docscribe/inline_rewriter/doc_block.rb', line 334

def build_priority(tag_order)
  normalized_tag_order(tag_order).each_with_index.to_h
end

.build_tag_entry(first, tag, entry_lines, index) ⇒ Docscribe::InlineRewriter::DocBlock::Entry

Note:

module_function: defines #build_tag_entry (visibility: private)

Build a tag Entry struct with metadata from the parsed tag line and continuation lines.

Parameters:

  • first (String) —

    the first (tag) line

  • tag (String) —

    the extracted tag name

  • entry_lines (Array<String>) —

    all lines belonging to this entry

  • index (Integer) —

    stable ordering index

Returns:



420
421
422
423
424
425
426
427
428
429
430
 
# File 'lib/docscribe/inline_rewriter/doc_block.rb', line 420

def build_tag_entry(first, tag, entry_lines, index)
  Entry.new(
    kind: :tag,
    tag: tag,
    lines: entry_lines,
    subject: extract_subject(first, tag),
    option_owner: extract_option_owner(first),
    generated: false,
    index: index
  )
end

.collect_continuation_lines(lines, start_idx, first, sortable_tags) ⇒ Array<String>

Note:

module_function: defines #collect_continuation_lines (visibility: private)

Collect the first tag line and all continuation lines belonging to the same entry.

Parameters:

  • lines (Array<String>) —

    comment block lines

  • start_idx (Integer) —

    index after the tag line

  • first (String) —

    the tag line itself

  • sortable_tags (Array<String>) —

    tag names treated as sortable

Returns:

  • (Array<String>) —

    all lines belonging to this entry



375
376
377
378
379
 
# File 'lib/docscribe/inline_rewriter/doc_block.rb', line 375

def collect_continuation_lines(lines, start_idx, first, sortable_tags)
  result = [first]
  add_continuation_lines(lines, start_idx, result, sortable_tags)
  result
end

.comment_line?(line) ⇒ Boolean

Note:

module_function: defines #comment_line? (visibility: private)

Whether a line is any comment line.

Parameters:

  • line (String) —

    the line to check

Returns:

  • (Boolean) 


542
543
544
 
# File 'lib/docscribe/inline_rewriter/doc_block.rb', line 542

def comment_line?(line)
  !!(line =~ /^\s*#/)
end

.consume_tag_entry(lines, start_idx, index:, sortable_tags:) ⇒ (Docscribe::InlineRewriter::DocBlock::Entry, Integer)

Note:

module_function: defines #consume_tag_entry (visibility: private)

Consume one sortable top-level tag entry and its continuation lines.

Continuation lines are comment lines that belong to the same logical tag entry until a new sortable tag line or a blank comment separator is encountered.

Parameters:

  • lines (Array<String>) —

    comment block lines

  • start_idx (Integer) —

    index to start scanning from

  • index (Integer) —

    stable original index

  • sortable_tags (Array<String>) —

    tag names treated as sortable

Returns:



358
359
360
361
362
363
364
365
 
# File 'lib/docscribe/inline_rewriter/doc_block.rb', line 358

def consume_tag_entry(lines, start_idx, index:, sortable_tags:)
  first = lines[start_idx]
  tag = extract_tag(first) || ''
  entry_lines = collect_continuation_lines(lines, start_idx + 1, first, sortable_tags)
  i = entry_lines.length + start_idx
  entry = build_tag_entry(first, tag, entry_lines, index)
  [entry, i]
end

.consume_tag_run(entries, idx) ⇒ (Array<Docscribe::InlineRewriter::DocBlock::Entry>, Integer)

Note:

module_function: defines #consume_tag_run (visibility: private)

Collect a contiguous run of :tag entries starting at idx.

Parameters:

Returns:



222
223
224
225
226
227
228
229
 
# File 'lib/docscribe/inline_rewriter/doc_block.rb', line 222

def consume_tag_run(entries, idx)
  run = [] #: Array[untyped]
  while idx < entries.length && entries[idx].kind == :tag
    run << entries[idx]
    idx += 1
  end
  [run, idx]
end

.continuation_candidate?(line, sortable_tags) ⇒ Boolean

Note:

module_function: defines #continuation_candidate? (visibility: private)

Check whether a line can serve as a continuation of the current tag entry.

Parameters:

  • line (String) —

    the line to check

  • sortable_tags (Array<String>) —

    tag names treated as sortable

Returns:

  • (Boolean) 


406
407
408
409
410
 
# File 'lib/docscribe/inline_rewriter/doc_block.rb', line 406

def continuation_candidate?(line, sortable_tags)
  !sortable_top_level_tag_line?(line, sortable_tags) &&
    !blank_comment_line?(line) &&
    continuation_comment_line?(line)
end

.continuation_comment_line?(line) ⇒ Boolean

Note:

module_function: defines #continuation_comment_line? (visibility: private)

Whether a comment line should be treated as a continuation of the previous tag entry.

Parameters:

  • line (String) —

    the line to check

Returns:

  • (Boolean) 


560
561
562
 
# File 'lib/docscribe/inline_rewriter/doc_block.rb', line 560

def continuation_comment_line?(line)
  !!(line =~ /^\s*#[ \t]{2,}\S/)
end

.extract_option_owner(line) ⇒ String?

Note:

module_function: defines #extract_option_owner (visibility: private)

Extract the owning options-hash param name from an ‘@option` line.

Parameters:

  • line (String) —

    the line to check

Returns:

  • (String?) 


503
504
505
 
# File 'lib/docscribe/inline_rewriter/doc_block.rb', line 503

def extract_option_owner(line)
  line[/^\s*#\s*@option\b\s+(\S+)/, 1]
end

.extract_param_name(line) ⇒ String?

Note:

module_function: defines #extract_param_name (visibility: private)

Extract a parameter name from a ‘@param` line.

Supports both:

  • ‘@param [Type] name`

  • ‘@param name [Type]`

Parameters:

  • line (String) —

    the line to check

Returns:

  • (String?) 


456
457
458
459
460
461
462
463
464
465
466
467
468
 
# File 'lib/docscribe/inline_rewriter/doc_block.rb', line 456

def extract_param_name(line)
  content = line.sub(/^\s*#\s*/, '')
  if (m = content.match(/@param\s+(\S+)\s+\[/))
    return m[1]
  elsif (m = content.match(/@param\s+\[/))
    end0 = m.end(0) #: Integer
    rest = content[(end0 - 1)..] #: String
    type_end = matching_close_bracket(rest)
    return name_after_bracket(rest, type_end) if type_end
  end

  nil
end

.extract_subject(line, tag) ⇒ String?

Note:

module_function: defines #extract_subject (visibility: private)

Extract the grouping subject for a sortable tag.

Currently only ‘@param` entries carry a subject, used to keep `@option` tags attached.

Parameters:

  • line (String) —

    the line to check

  • tag (String?) —

    the extracted tag name

Returns:

  • (String?) 


440
441
442
443
444
445
 
# File 'lib/docscribe/inline_rewriter/doc_block.rb', line 440

def extract_subject(line, tag)
  case tag
  when 'param'
    extract_param_name(line)
  end
end

.extract_tag(line) ⇒ String?

Note:

module_function: defines #extract_tag (visibility: private)

Extract a top-level tag name without the leading ‘@`.

Parameters:

  • line (String) —

    the line to check

Returns:

  • (String?) 


524
525
526
 
# File 'lib/docscribe/inline_rewriter/doc_block.rb', line 524

def extract_tag(line)
  line[/^\s*#\s*@(\w+)/, 1]
end

.filter_existing_entries(entries, filter_existing) ⇒ Array<Docscribe::InlineRewriter::DocBlock::Entry>

Note:

module_function: defines #filter_existing_entries (visibility: private)

Remove existing entries matching the filter criteria (param names or return tag).

Parameters:

Returns:



93
94
95
96
97
98
99
 
# File 'lib/docscribe/inline_rewriter/doc_block.rb', line 93

def filter_existing_entries(entries, filter_existing)
  filter_param_names = filter_existing[:param_names] || []
  filter_return = !!filter_existing[:return]
  entries.reject do |entry|
    filter_param_entry?(entry, filter_param_names) || filter_return_entry?(entry, filter_return)
  end
end

.filter_param_entry?(entry, param_names) ⇒ Boolean

Note:

module_function: defines #filter_param_entry? (visibility: private)

Check whether an entry is a @param tag whose name is in the filter list.

Parameters:

Returns:

  • (Boolean) 


107
108
109
 
# File 'lib/docscribe/inline_rewriter/doc_block.rb', line 107

def filter_param_entry?(entry, param_names)
  entry.kind == :tag && entry.tag == 'param' && param_names.include?(entry.subject)
end

.filter_return_entry?(entry, filter_return) ⇒ Boolean

Note:

module_function: defines #filter_return_entry? (visibility: private)

Check whether an entry is a @return tag that should be filtered.

Parameters:

Returns:

  • (Boolean) 


117
118
119
 
# File 'lib/docscribe/inline_rewriter/doc_block.rb', line 117

def filter_return_entry?(entry, filter_return)
  entry.kind == :tag && entry.tag == 'return' && filter_return
end

.group_entries_loop(entries, groups) ⇒ void

Note:

module_function: defines #group_entries_loop (visibility: private)

This method returns an undefined value.

Iterate entries to build sorted groups, attaching @option entries to their @param.

Parameters:



273
274
275
276
 
# File 'lib/docscribe/inline_rewriter/doc_block.rb', line 273

def group_entries_loop(entries, groups)
  idx = 0
  idx = group_one_entry(entries, idx, groups) while idx < entries.length
end

.group_one_entry(entries, idx, groups) ⇒ Integer

Note:

module_function: defines #group_one_entry (visibility: private)

Group a single entry, creating a param group with @option children if applicable.

Parameters:

Returns:

  • (Integer) —

    next index after processing the group



285
286
287
288
289
290
291
292
293
294
295
 
# File 'lib/docscribe/inline_rewriter/doc_block.rb', line 285

def group_one_entry(entries, idx, groups)
  entry = entries[idx]
  if entry.tag == 'param'
    group = build_param_group(entries, idx, entry)
    groups << group
    idx + group.size
  else
    groups << [entry]
    idx + 1
  end
end

.group_priority(group, priority) ⇒ Integer

Note:

module_function: defines #group_priority (visibility: private)

Compute the priority of a grouped sortable unit.

Parameters:

Returns:

  • (Integer) 


325
326
327
 
# File 'lib/docscribe/inline_rewriter/doc_block.rb', line 325

def group_priority(group, priority)
  priority.fetch(group.first.tag, priority.length)
end

.matching_close_bracket(str) ⇒ Integer?

Note:

module_function: defines #matching_close_bracket (visibility: private)

Find the index of the matching close bracket for an outermost ‘[`.

Parameters:

  • str (String) —

    string to scan

Returns:

  • (Integer?) 


485
486
487
488
489
490
491
492
493
494
495
496
 
# File 'lib/docscribe/inline_rewriter/doc_block.rb', line 485

def matching_close_bracket(str)
  depth = 0
  str.each_char.with_index do |c, i|
    case c
    when '[' then depth += 1
    when ']'
      depth -= 1
      return i if depth.zero?
    end
  end
  nil
end

.merge(existing_lines, missing_lines:, sort_tags:, tag_order:, filter_existing: {}) ⇒ Array<String>

Note:

module_function: defines #merge (visibility: private)

Merge existing doc lines with newly generated missing tag lines.

Existing text is preserved exactly. If sorting is enabled, only sortable tag runs are normalized according to the configured tag order.

Parameters:

  • existing_lines (Array<String>) —

    existing doc block lines

  • missing_lines (Array<String>) —

    generated tag lines to add

  • sort_tags (Boolean) —

    whether sortable tags should be reordered

  • tag_order (Array<String>) —

    configured sortable tag order

  • filter_existing (Hash<Symbol, Object>) (defaults to: {}) —

    tags to filter from existing block

Returns:

  • (Array<String>) 


65
66
67
68
69
70
71
72
 
# File 'lib/docscribe/inline_rewriter/doc_block.rb', line 65

def merge(existing_lines, missing_lines:, sort_tags:, tag_order:, filter_existing: {})
  existing_entries = parse(existing_lines, tag_order: tag_order)
  missing_entries = parse_generated(missing_lines, tag_order: tag_order)
  existing_entries = filter_existing_entries(existing_entries, filter_existing)
  entries = existing_entries + missing_entries
  entries = sort(entries, tag_order: tag_order) if sort_tags
  render(entries)
end

.name_after_bracket(rest, type_end) ⇒ String?

Note:

module_function: defines #name_after_bracket (visibility: private)

Extract name after type bracket

Parameters:

  • rest (String) —

    remaining tag content

  • type_end (Integer) —

    closing bracket position

Returns:

  • (String?) 


476
477
478
 
# File 'lib/docscribe/inline_rewriter/doc_block.rb', line 476

def name_after_bracket(rest, type_end)
  rest[(type_end + 1)..].to_s.strip.split(/\s+/).first
end

.normalized_tag_order(tag_order) ⇒ Array<String>

Note:

module_function: defines #normalized_tag_order (visibility: private)

Normalize configured tag names by removing leading ‘@`.

Parameters:

  • tag_order (Array<String>) —

    configured sortable tag order

Returns:

  • (Array<String>) 


343
344
345
 
# File 'lib/docscribe/inline_rewriter/doc_block.rb', line 343

def normalized_tag_order(tag_order)
  Array(tag_order).map { |t| t.to_s.sub(/\A@/, '') }
end

.parse(lines, tag_order:) ⇒ Array<Docscribe::InlineRewriter::DocBlock::Entry>

Note:

module_function: defines #parse (visibility: private)

Parse a doc block into structured entries.

Only tags listed in ‘tag_order` are treated as sortable tag entries. Other lines become `:other` entries and act as sort boundaries.

Parameters:

  • lines (Array<String>) —

    comment block lines

  • tag_order (Array<String>) —

    configured sortable tag order

Returns:



130
131
132
133
 
# File 'lib/docscribe/inline_rewriter/doc_block.rb', line 130

def parse(lines, tag_order:)
  sortable_tags = normalized_tag_order(tag_order)
  parse_lines(lines, sortable_tags, entries: [], index: 0)
end

.parse_generated(lines, tag_order:) ⇒ Array<Docscribe::InlineRewriter::DocBlock::Entry>

Note:

module_function: defines #parse_generated (visibility: private)

Parse generated missing tag lines and mark them as generated entries.

Parameters:

  • lines (Array<String>) —

    generated lines

  • tag_order (Array<String>) —

    configured sortable tag order

Returns:



80
81
82
83
84
85
 
# File 'lib/docscribe/inline_rewriter/doc_block.rb', line 80

def parse_generated(lines, tag_order:)
  parse(lines, tag_order: tag_order).map do |entry|
    entry.generated = true if entry.kind == :tag
    entry
  end
end

.parse_lines(lines, sortable_tags, entries:, index:) ⇒ Array<Docscribe::InlineRewriter::DocBlock::Entry>

Note:

module_function: defines #parse_lines (visibility: private)

Iterate through all lines and parse each one into a structured entry.

Parameters:

  • lines (Array<String>) —

    comment block lines

  • sortable_tags (Array<String>) —

    tag names treated as sortable

  • entries (Array<Docscribe::InlineRewriter::DocBlock::Entry>) —

    accumulated parsed entries

  • index (Integer) —

    stable ordering index for entries

Returns:



143
144
145
146
147
148
149
150
 
# File 'lib/docscribe/inline_rewriter/doc_block.rb', line 143

def parse_lines(lines, sortable_tags, entries:, index:)
  idx = 0
  while idx < lines.length
    idx = parse_one_line(lines, idx, sortable_tags, entries, index)
    index += 1
  end
  entries
end

.parse_one_line(lines, idx, sortable_tags, entries, index) ⇒ Integer

Note:

module_function: defines #parse_one_line (visibility: private)

Parse a single line as a sortable tag entry or non-tag content.

Parameters:

  • lines (Array<String>) —

    comment block lines

  • idx (Integer) —

    current line index

  • sortable_tags (Array<String>) —

    tag names treated as sortable

  • entries (Array<Docscribe::InlineRewriter::DocBlock::Entry>) —

    accumulated parsed entries

  • index (Integer) —

    stable ordering index for entries

Returns:

  • (Integer) —

    next line index after parsing



161
162
163
164
165
166
167
168
169
170
 
# File 'lib/docscribe/inline_rewriter/doc_block.rb', line 161

def parse_one_line(lines, idx, sortable_tags, entries, index)
  if sortable_top_level_tag_line?(lines[idx], sortable_tags)
    entry, idx = consume_tag_entry(lines, idx, index: index, sortable_tags: sortable_tags)
    entries << entry
  else
    entries << build_other_entry(lines[idx], index)
    idx += 1
  end
  idx
end

.render(entries) ⇒ Array<String>

Note:

module_function: defines #render (visibility: private)

Render parsed entries back into comment lines.

Parameters:

Returns:

  • (Array<String>) 


236
237
238
 
# File 'lib/docscribe/inline_rewriter/doc_block.rb', line 236

def render(entries)
  entries.flat_map(&:lines)
end

.sort(entries, tag_order:) ⇒ Array<Docscribe::InlineRewriter::DocBlock::Entry>

Note:

module_function: defines #sort (visibility: private)

Sort parsed entries by configured tag order, preserving boundaries between tag runs.

Parameters:

Returns:



188
189
190
191
192
193
 
# File 'lib/docscribe/inline_rewriter/doc_block.rb', line 188

def sort(entries, tag_order:)
  out = [] #: Array[untyped]
  priority = build_priority(tag_order)
  sort_loop(entries, out, priority)
  out
end

.sort_loop(entries, out, priority) ⇒ void

Note:

module_function: defines #sort_loop (visibility: private)

This method returns an undefined value.

Iterate entries, sorting contiguous tag runs while preserving non-tag boundaries.

Parameters:



202
203
204
205
206
207
208
209
210
211
212
213
214
 
# File 'lib/docscribe/inline_rewriter/doc_block.rb', line 202

def sort_loop(entries, out, priority)
  idx = 0

  while idx < entries.length
    if entries[idx].kind == :tag
      run, idx = consume_tag_run(entries, idx)
      out.concat(sort_run(run, priority: priority))
    else
      out << entries[idx]
      idx += 1
    end
  end
end

.sort_run(entries, priority:) ⇒ Array<Docscribe::InlineRewriter::DocBlock::Entry>

Note:

module_function: defines #sort_run (visibility: private)

Sort one contiguous run of sortable tag entries.

Parameters:

Returns:



246
247
248
249
250
251
252
253
254
 
# File 'lib/docscribe/inline_rewriter/doc_block.rb', line 246

def sort_run(entries, priority:)
  groups = build_groups(entries)

  groups
    .each_with_index
    .sort_by { |(group, idx)| [group_priority(group, priority), idx] }
    .map(&:first)
    .flatten
end

.sortable_top_level_tag_line?(line, sortable_tags) ⇒ Boolean

Note:

module_function: defines #sortable_top_level_tag_line? (visibility: private)

Whether a line is a sortable top-level tag line.

Parameters:

  • line (String) —

    the line to check

  • sortable_tags (Array<String>) —

    tag names treated as sortable

Returns:

  • (Boolean) 


513
514
515
516
517
 
# File 'lib/docscribe/inline_rewriter/doc_block.rb', line 513

def sortable_top_level_tag_line?(line, sortable_tags)
  return false unless top_level_tag_line?(line)

  sortable_tags.include?(extract_tag(line))
end

.top_level_tag_line?(line) ⇒ Boolean

Note:

module_function: defines #top_level_tag_line? (visibility: private)

Whether a line begins a top-level YARD-style tag.

Parameters:

  • line (String) —

    the line to check

Returns:

  • (Boolean) 


533
534
535
 
# File 'lib/docscribe/inline_rewriter/doc_block.rb', line 533

def top_level_tag_line?(line)
  !!(line =~ /^\s*#\s*@\w+/)
end