docscribe 1.4.2 → 1.5.0

data/lib/docscribe/inline_rewriter/doc_block.rb

@@ -12,38 +12,33 @@ module Docscribe
     module DocBlock
       module_function
 
-      # One parsed entry inside a doc block.
-      #
-      # `kind` is:
-      # - `:tag` for a sortable top-level tag entry
-      # - `:other` for prose/separators/non-sortable content
       # @!attribute [rw] kind
-      #   @return [Object]
-      #   @param [Object] value
+      #   @return [Symbol]
+      #   @param [Symbol] value
       #
       # @!attribute [rw] tag
-      #   @return [Object]
-      #   @param [Object] value
+      #   @return [String]
+      #   @param [String] value
       #
       # @!attribute [rw] lines
-      #   @return [Object]
-      #   @param [Object] value
+      #   @return [Array<String>]
+      #   @param [Array<String>] value
       #
       # @!attribute [rw] subject
-      #   @return [Object]
-      #   @param [Object] value
+      #   @return [String?]
+      #   @param [String?] value
       #
       # @!attribute [rw] option_owner
-      #   @return [Object]
-      #   @param [Object] value
+      #   @return [String?]
+      #   @param [String?] value
       #
       # @!attribute [rw] generated
-      #   @return [Object]
-      #   @param [Object] value
+      #   @return [Boolean]
+      #   @param [Boolean] value
       #
       # @!attribute [rw] index
-      #   @return [Object]
-      #   @param [Object] value
+      #   @return [Integer]
+      #   @param [Integer] value
       Entry = Struct.new(
         :kind,
         :tag,
@@ -60,12 +55,12 @@ module Docscribe
       # Existing text is preserved exactly. If sorting is enabled, only sortable tag runs
       # are normalized according to the configured tag order.
       #
-      # @note module_function: when included, also defines #merge (instance visibility: private)
+      # @note module_function: defines #merge (visibility: private)
       # @param [Array<String>] existing_lines existing doc block lines
       # @param [Array<String>] missing_lines generated tag lines to add
       # @param [Boolean] sort_tags whether sortable tags should be reordered
       # @param [Array<String>] tag_order configured sortable tag order
-      # @param [Hash] filter_existing tags to filter from existing block
+      # @param [Hash<Symbol, Object>] filter_existing tags to filter from existing block
       # @return [Array<String>]
       def merge(existing_lines, missing_lines:, sort_tags:, tag_order:, filter_existing: {})
         existing_entries = parse(existing_lines, tag_order: tag_order)
@@ -78,10 +73,10 @@ module Docscribe
 
       # Parse generated missing tag lines and mark them as generated entries.
       #
-      # @note module_function: when included, also defines #parse_generated (instance visibility: private)
+      # @note module_function: defines #parse_generated (visibility: private)
       # @param [Array<String>] lines generated lines
       # @param [Array<String>] tag_order configured sortable tag order
-      # @return [Array<Entry>]
+      # @return [Array<Docscribe::InlineRewriter::DocBlock::Entry>]
       def parse_generated(lines, tag_order:)
         parse(lines, tag_order: tag_order).map do |entry|
           entry.generated = true if entry.kind == :tag
@@ -91,10 +86,10 @@ module Docscribe
 
       # Remove existing entries matching the filter criteria (param names or return tag).
       #
-      # @note module_function: when included, also defines #filter_existing_entries (instance visibility: private)
-      # @param [Array<Entry>] entries parsed existing entries
-      # @param [Hash] filter_existing filter specification with :param_names and :return keys
-      # @return [Array<Entry>] filtered entries
+      # @note module_function: defines #filter_existing_entries (visibility: private)
+      # @param [Array<Docscribe::InlineRewriter::DocBlock::Entry>] entries parsed existing entries
+      # @param [Hash<Symbol, Object>] filter_existing filter specification with :param_names and :return keys
+      # @return [Array<Docscribe::InlineRewriter::DocBlock::Entry>] filtered entries
       def filter_existing_entries(entries, filter_existing)
         filter_param_names = filter_existing[:param_names] || []
         filter_return = !!filter_existing[:return]
@@ -105,8 +100,8 @@ module Docscribe
 
       # Check whether an entry is a @param tag whose name is in the filter list.
       #
-      # @note module_function: when included, also defines #filter_param_entry? (instance visibility: private)
-      # @param [Entry] entry the entry to check
+      # @note module_function: defines #filter_param_entry? (visibility: private)
+      # @param [Docscribe::InlineRewriter::DocBlock::Entry] entry the entry to check
       # @param [Array<String>] param_names parameter names to filter
       # @return [Boolean]
       def filter_param_entry?(entry, param_names)
@@ -115,8 +110,8 @@ module Docscribe
 
       # Check whether an entry is a @return tag that should be filtered.
       #
-      # @note module_function: when included, also defines #filter_return_entry? (instance visibility: private)
-      # @param [Entry] entry the entry to check
+      # @note module_function: defines #filter_return_entry? (visibility: private)
+      # @param [Docscribe::InlineRewriter::DocBlock::Entry] entry the entry to check
       # @param [Boolean] filter_return whether return tags should be filtered
       # @return [Boolean]
       def filter_return_entry?(entry, filter_return)
@@ -128,10 +123,10 @@ module Docscribe
       # Only tags listed in `tag_order` are treated as sortable tag entries.
       # Other lines become `:other` entries and act as sort boundaries.
       #
-      # @note module_function: when included, also defines #parse (instance visibility: private)
+      # @note module_function: defines #parse (visibility: private)
       # @param [Array<String>] lines comment block lines
       # @param [Array<String>] tag_order configured sortable tag order
-      # @return [Array<Entry>]
+      # @return [Array<Docscribe::InlineRewriter::DocBlock::Entry>]
       def parse(lines, tag_order:)
         sortable_tags = normalized_tag_order(tag_order)
         parse_lines(lines, sortable_tags, entries: [], index: 0)
@@ -139,12 +134,12 @@ module Docscribe
 
       # Iterate through all lines and parse each one into a structured entry.
       #
-      # @note module_function: when included, also defines #parse_lines (instance visibility: private)
+      # @note module_function: defines #parse_lines (visibility: private)
       # @param [Array<String>] lines comment block lines
       # @param [Array<String>] sortable_tags tag names treated as sortable
-      # @param [Array<Entry>] entries accumulated parsed entries
+      # @param [Array<Docscribe::InlineRewriter::DocBlock::Entry>] entries accumulated parsed entries
       # @param [Integer] index stable ordering index for entries
-      # @return [Array<Entry>]
+      # @return [Array<Docscribe::InlineRewriter::DocBlock::Entry>]
       def parse_lines(lines, sortable_tags, entries:, index:)
         idx = 0
         while idx < lines.length
@@ -156,11 +151,11 @@ module Docscribe
 
       # Parse a single line as a sortable tag entry or non-tag content.
       #
-      # @note module_function: when included, also defines #parse_one_line (instance visibility: private)
+      # @note module_function: defines #parse_one_line (visibility: private)
       # @param [Array<String>] lines comment block lines
       # @param [Integer] idx current line index
       # @param [Array<String>] sortable_tags tag names treated as sortable
-      # @param [Array<Entry>] entries accumulated parsed entries
+      # @param [Array<Docscribe::InlineRewriter::DocBlock::Entry>] entries accumulated parsed entries
       # @param [Integer] index stable ordering index for entries
       # @return [Integer] next line index after parsing
       def parse_one_line(lines, idx, sortable_tags, entries, index)
@@ -176,20 +171,20 @@ module Docscribe
 
       # Create an :other entry for a non-tag line (prose, blank separators, etc.).
       #
-      # @note module_function: when included, also defines #build_other_entry (instance visibility: private)
+      # @note module_function: defines #build_other_entry (visibility: private)
       # @param [String] line the comment line
       # @param [Integer] index stable ordering index
-      # @return [Entry]
+      # @return [Docscribe::InlineRewriter::DocBlock::Entry]
       def build_other_entry(line, index)
         Entry.new(kind: :other, lines: [line], generated: false, index: index)
       end
 
       # Sort parsed entries by configured tag order, preserving boundaries between tag runs.
       #
-      # @note module_function: when included, also defines #sort (instance visibility: private)
-      # @param [Array<Entry>] entries parsed entries
+      # @note module_function: defines #sort (visibility: private)
+      # @param [Array<Docscribe::InlineRewriter::DocBlock::Entry>] entries parsed entries
       # @param [Array<String>] tag_order configured sortable tag order
-      # @return [Array<Entry>]
+      # @return [Array<Docscribe::InlineRewriter::DocBlock::Entry>]
       def sort(entries, tag_order:)
         out = [] #: Array[untyped]
         priority = build_priority(tag_order)
@@ -199,10 +194,10 @@ module Docscribe
 
       # Iterate entries, sorting contiguous tag runs while preserving non-tag boundaries.
       #
-      # @note module_function: when included, also defines #sort_loop (instance visibility: private)
-      # @param [Array<Entry>] entries parsed entries to sort
-      # @param [Array<Entry>] out output array for sorted entries
-      # @param [Hash{String=>Integer}] priority tag priority map
+      # @note module_function: defines #sort_loop (visibility: private)
+      # @param [Array<Docscribe::InlineRewriter::DocBlock::Entry>] entries parsed entries to sort
+      # @param [Array<Docscribe::InlineRewriter::DocBlock::Entry>] out output array for sorted entries
+      # @param [Hash<String, Integer>] priority tag priority map
       # @return [void]
       def sort_loop(entries, out, priority)
         idx = 0
@@ -220,10 +215,10 @@ module Docscribe
 
       # Collect a contiguous run of :tag entries starting at idx.
       #
-      # @note module_function: when included, also defines #consume_tag_run (instance visibility: private)
-      # @param [Array<Entry>] entries parsed entries
+      # @note module_function: defines #consume_tag_run (visibility: private)
+      # @param [Array<Docscribe::InlineRewriter::DocBlock::Entry>] entries parsed entries
       # @param [Integer] idx start index
-      # @return [Array<(Array<Entry>, Integer)>] the tag run and next index
+      # @return [(Array<Docscribe::InlineRewriter::DocBlock::Entry>, Integer)]
       def consume_tag_run(entries, idx)
         run = [] #: Array[untyped]
         while idx < entries.length && entries[idx].kind == :tag
@@ -235,8 +230,8 @@ module Docscribe
 
       # Render parsed entries back into comment lines.
       #
-      # @note module_function: when included, also defines #render (instance visibility: private)
-      # @param [Array<Entry>] entries
+      # @note module_function: defines #render (visibility: private)
+      # @param [Array<Docscribe::InlineRewriter::DocBlock::Entry>] entries contiguous tag run entries
       # @return [Array<String>]
       def render(entries)
         entries.flat_map(&:lines)
@@ -244,10 +239,10 @@ module Docscribe
 
       # Sort one contiguous run of sortable tag entries.
       #
-      # @note module_function: when included, also defines #sort_run (instance visibility: private)
-      # @param [Array<Entry>] entries contiguous tag run
-      # @param [Hash{String=>Integer}] priority tag priority map
-      # @return [Array<Entry>]
+      # @note module_function: defines #sort_run (visibility: private)
+      # @param [Array<Docscribe::InlineRewriter::DocBlock::Entry>] entries contiguous tag run
+      # @param [Hash<String, Integer>] priority tag priority map
+      # @return [Array<Docscribe::InlineRewriter::DocBlock::Entry>]
       def sort_run(entries, priority:)
         groups = build_groups(entries)
 
@@ -260,9 +255,9 @@ module Docscribe
 
       # Group entries so related `@option` tags stay attached to their owning `@param`.
       #
-      # @note module_function: when included, also defines #build_groups (instance visibility: private)
-      # @param [Array<Entry>] entries
-      # @return [Array<Array<Entry>>]
+      # @note module_function: defines #build_groups (visibility: private)
+      # @param [Array<Docscribe::InlineRewriter::DocBlock::Entry>] entries contiguous tag run entries
+      # @return [Array<Array<Docscribe::InlineRewriter::DocBlock::Entry>>]
       def build_groups(entries)
         groups = [] #: Array[untyped]
         group_entries_loop(entries, groups)
@@ -271,9 +266,9 @@ module Docscribe
 
       # Iterate entries to build sorted groups, attaching @option entries to their @param.
       #
-      # @note module_function: when included, also defines #group_entries_loop (instance visibility: private)
-      # @param [Array<Entry>] entries contiguous tag run entries
-      # @param [Array<Array<Entry>>] groups accumulated groups
+      # @note module_function: defines #group_entries_loop (visibility: private)
+      # @param [Array<Docscribe::InlineRewriter::DocBlock::Entry>] entries contiguous tag run entries
+      # @param [Array<Array<Docscribe::InlineRewriter::DocBlock::Entry>>] groups accumulated groups
       # @return [void]
       def group_entries_loop(entries, groups)
         idx = 0
@@ -282,10 +277,10 @@ module Docscribe
 
       # Group a single entry, creating a param group with @option children if applicable.
       #
-      # @note module_function: when included, also defines #group_one_entry (instance visibility: private)
-      # @param [Array<Entry>] entries contiguous tag run entries
+      # @note module_function: defines #group_one_entry (visibility: private)
+      # @param [Array<Docscribe::InlineRewriter::DocBlock::Entry>] entries contiguous tag run entries
       # @param [Integer] idx current entry index
-      # @param [Array<Array<Entry>>] groups accumulated groups
+      # @param [Array<Array<Docscribe::InlineRewriter::DocBlock::Entry>>] groups accumulated groups
       # @return [Integer] next index after processing the group
       def group_one_entry(entries, idx, groups)
         entry = entries[idx]
@@ -301,11 +296,11 @@ module Docscribe
 
       # Build a group starting with a @param entry and including its following @option entries.
       #
-      # @note module_function: when included, also defines #build_param_group (instance visibility: private)
-      # @param [Array<Entry>] entries contiguous tag run entries
+      # @note module_function: defines #build_param_group (visibility: private)
+      # @param [Array<Docscribe::InlineRewriter::DocBlock::Entry>] entries contiguous tag run entries
       # @param [Integer] idx index of the @param entry
-      # @param [Entry] entry the @param entry
-      # @return [Array<Entry>] the param group including @option children
+      # @param [Docscribe::InlineRewriter::DocBlock::Entry] entry the @param entry
+      # @return [Array<Docscribe::InlineRewriter::DocBlock::Entry>] the param group including @option children
       def build_param_group(entries, idx, entry)
         group = [entry]
         idx += 1
@@ -323,9 +318,9 @@ module Docscribe
 
       # Compute the priority of a grouped sortable unit.
       #
-      # @note module_function: when included, also defines #group_priority (instance visibility: private)
-      # @param [Array<Entry>] group
-      # @param [Hash{String=>Integer}] priority
+      # @note module_function: defines #group_priority (visibility: private)
+      # @param [Array<Docscribe::InlineRewriter::DocBlock::Entry>] group tag group array
+      # @param [Hash<String, Integer>] priority tag priority map
       # @return [Integer]
       def group_priority(group, priority)
         priority.fetch(group.first.tag, priority.length)
@@ -333,17 +328,17 @@ module Docscribe
 
       # Build a tag priority map from configured order.
       #
-      # @note module_function: when included, also defines #build_priority (instance visibility: private)
-      # @param [Array<String>] tag_order
-      # @return [Hash{String=>Integer}]
+      # @note module_function: defines #build_priority (visibility: private)
+      # @param [Array<String>] tag_order configured sortable tag order
+      # @return [Hash<String, Integer>]
       def build_priority(tag_order)
         normalized_tag_order(tag_order).each_with_index.to_h
       end
 
       # Normalize configured tag names by removing leading `@`.
       #
-      # @note module_function: when included, also defines #normalized_tag_order (instance visibility: private)
-      # @param [Array<String>] tag_order
+      # @note module_function: defines #normalized_tag_order (visibility: private)
+      # @param [Array<String>] tag_order configured sortable tag order
       # @return [Array<String>]
       def normalized_tag_order(tag_order)
         Array(tag_order).map { |t| t.to_s.sub(/\A@/, '') }
@@ -354,15 +349,15 @@ module Docscribe
       # 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.
       #
-      # @note module_function: when included, also defines #consume_tag_entry (instance visibility: private)
-      # @param [Array<String>] lines
-      # @param [Integer] start_idx
+      # @note module_function: defines #consume_tag_entry (visibility: private)
+      # @param [Array<String>] lines comment block lines
+      # @param [Integer] start_idx index to start scanning from
       # @param [Integer] index stable original index
-      # @param [Array<String>] sortable_tags
-      # @return [Array<(Entry, Integer)>] parsed entry and next index
+      # @param [Array<String>] sortable_tags tag names treated as sortable
+      # @return [(Docscribe::InlineRewriter::DocBlock::Entry, Integer)]
       def consume_tag_entry(lines, start_idx, index:, sortable_tags:)
         first = lines[start_idx]
-        tag = extract_tag(first)
+        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)
@@ -371,7 +366,7 @@ module Docscribe
 
       # Collect the first tag line and all continuation lines belonging to the same entry.
       #
-      # @note module_function: when included, also defines #collect_continuation_lines (instance visibility: private)
+      # @note module_function: defines #collect_continuation_lines (visibility: private)
       # @param [Array<String>] lines comment block lines
       # @param [Integer] start_idx index after the tag line
       # @param [String] first the tag line itself
@@ -385,7 +380,7 @@ module Docscribe
 
       # Append continuation lines to the result array until a non-continuation line is found.
       #
-      # @note module_function: when included, also defines #add_continuation_lines (instance visibility: private)
+      # @note module_function: defines #add_continuation_lines (visibility: private)
       # @param [Array<String>] lines comment block lines
       # @param [Integer] start_idx index to start scanning from
       # @param [Array<String>] result accumulated entry lines
@@ -404,7 +399,7 @@ module Docscribe
 
       # Check whether a line can serve as a continuation of the current tag entry.
       #
-      # @note module_function: when included, also defines #continuation_candidate? (instance visibility: private)
+      # @note module_function: defines #continuation_candidate? (visibility: private)
       # @param [String] line the line to check
       # @param [Array<String>] sortable_tags tag names treated as sortable
       # @return [Boolean]
@@ -416,12 +411,12 @@ module Docscribe
 
       # Build a tag Entry struct with metadata from the parsed tag line and continuation lines.
       #
-      # @note module_function: when included, also defines #build_tag_entry (instance visibility: private)
+      # @note module_function: defines #build_tag_entry (visibility: private)
       # @param [String] first the first (tag) line
-      # @param [String, nil] tag the extracted tag name
+      # @param [String] tag the extracted tag name
       # @param [Array<String>] entry_lines all lines belonging to this entry
       # @param [Integer] index stable ordering index
-      # @return [Entry]
+      # @return [Docscribe::InlineRewriter::DocBlock::Entry]
       def build_tag_entry(first, tag, entry_lines, index)
         Entry.new(
           kind: :tag,
@@ -438,10 +433,10 @@ module Docscribe
       #
       # Currently only `@param` entries carry a subject, used to keep `@option` tags attached.
       #
-      # @note module_function: when included, also defines #extract_subject (instance visibility: private)
-      # @param [String] line
-      # @param [String] tag
-      # @return [String, nil]
+      # @note module_function: defines #extract_subject (visibility: private)
+      # @param [String] line the line to check
+      # @param [String?] tag the extracted tag name
+      # @return [String?]
       def extract_subject(line, tag)
         case tag
         when 'param'
@@ -455,30 +450,65 @@ module Docscribe
       # - `@param [Type] name`
       # - `@param name [Type]`
       #
-      # @note module_function: when included, also defines #extract_param_name (instance visibility: private)
-      # @param [String] line
-      # @return [String, nil]
+      # @note module_function: defines #extract_param_name (visibility: private)
+      # @param [String] line the line to check
+      # @return [String?]
       def extract_param_name(line)
-        return Regexp.last_match(1) if line =~ /^\s*#\s*@param\b\s+\[[^\]]+\]\s+(\S+)/
-        return Regexp.last_match(1) if line =~ /^\s*#\s*@param\b\s+(\S+)\s+\[[^\]]+\]/
+        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 name after type bracket
+      #
+      # @note module_function: defines #name_after_bracket (visibility: private)
+      # @param [String] rest remaining tag content
+      # @param [Integer] type_end closing bracket position
+      # @return [String?]
+      def name_after_bracket(rest, type_end)
+        rest[(type_end + 1)..].to_s.strip.split(/\s+/).first
+      end
 
+      # Find the index of the matching close bracket for an outermost `[`.
+      #
+      # @note module_function: defines #matching_close_bracket (visibility: private)
+      # @param [String] str string to scan
+      # @return [Integer?]
+      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
 
       # Extract the owning options-hash param name from an `@option` line.
       #
-      # @note module_function: when included, also defines #extract_option_owner (instance visibility: private)
-      # @param [String] line
-      # @return [String, nil]
+      # @note module_function: defines #extract_option_owner (visibility: private)
+      # @param [String] line the line to check
+      # @return [String?]
       def extract_option_owner(line)
         line[/^\s*#\s*@option\b\s+(\S+)/, 1]
       end
 
       # Whether a line is a sortable top-level tag line.
       #
-      # @note module_function: when included, also defines #sortable_top_level_tag_line? (instance visibility: private)
-      # @param [String] line
-      # @param [Array<String>] sortable_tags
+      # @note module_function: defines #sortable_top_level_tag_line? (visibility: private)
+      # @param [String] line the line to check
+      # @param [Array<String>] sortable_tags tag names treated as sortable
       # @return [Boolean]
       def sortable_top_level_tag_line?(line, sortable_tags)
         return false unless top_level_tag_line?(line)
@@ -488,17 +518,17 @@ module Docscribe
 
       # Extract a top-level tag name without the leading `@`.
       #
-      # @note module_function: when included, also defines #extract_tag (instance visibility: private)
-      # @param [String] line
-      # @return [String, nil]
+      # @note module_function: defines #extract_tag (visibility: private)
+      # @param [String] line the line to check
+      # @return [String?]
       def extract_tag(line)
         line[/^\s*#\s*@(\w+)/, 1]
       end
 
       # Whether a line begins a top-level YARD-style tag.
       #
-      # @note module_function: when included, also defines #top_level_tag_line? (instance visibility: private)
-      # @param [String] line
+      # @note module_function: defines #top_level_tag_line? (visibility: private)
+      # @param [String] line the line to check
       # @return [Boolean]
       def top_level_tag_line?(line)
         !!(line =~ /^\s*#\s*@\w+/)
@@ -506,8 +536,8 @@ module Docscribe
 
       # Whether a line is any comment line.
       #
-      # @note module_function: when included, also defines #comment_line? (instance visibility: private)
-      # @param [String] line
+      # @note module_function: defines #comment_line? (visibility: private)
+      # @param [String] line the line to check
       # @return [Boolean]
       def comment_line?(line)
         !!(line =~ /^\s*#/)
@@ -515,8 +545,8 @@ module Docscribe
 
       # Whether a line is a blank comment separator such as `#`.
       #
-      # @note module_function: when included, also defines #blank_comment_line? (instance visibility: private)
-      # @param [String] line
+      # @note module_function: defines #blank_comment_line? (visibility: private)
+      # @param [String] line the line to check
       # @return [Boolean]
       def blank_comment_line?(line)
         !!(line =~ /^\s*#\s*$/)
@@ -524,8 +554,8 @@ module Docscribe
 
       # Whether a comment line should be treated as a continuation of the previous tag entry.
       #
-      # @note module_function: when included, also defines #continuation_comment_line? (instance visibility: private)
-      # @param [String] line
+      # @note module_function: defines #continuation_comment_line? (visibility: private)
+      # @param [String] line the line to check
       # @return [Boolean]
       def continuation_comment_line?(line)
         !!(line =~ /^\s*#[ \t]{2,}\S/)