docscribe 1.4.1 → 1.5.0

data/lib/docscribe/inline_rewriter/source_helpers.rb

@@ -12,8 +12,8 @@ module Docscribe
 
       # Extract the method name from a `:def` or `:defs` node.
       #
-      # @note module_function: when included, also defines #node_name (instance visibility: private)
-      # @param [Parser::AST::Node] node
+      # @note module_function: defines #node_name (visibility: private)
+      # @param [Parser::AST::Node] node def or defs AST node
       # @return [Symbol, nil]
       def node_name(node)
         case node.type
@@ -26,9 +26,9 @@ module Docscribe
       #
       # Used as the insertion point for generated documentation.
       #
-      # @note module_function: when included, also defines #line_start_range (instance visibility: private)
-      # @param [Parser::Source::Buffer] buffer
-      # @param [Parser::AST::Node] node
+      # @note module_function: defines #line_start_range (visibility: private)
+      # @param [Parser::Source::Buffer] buffer source buffer for range
+      # @param [Parser::AST::Node] node target AST node
       # @return [Parser::Source::Range]
       def line_start_range(buffer, node)
         start_pos = node.loc.expression.begin_pos
@@ -47,49 +47,22 @@ module Docscribe
       #
       # Returns nil if no doc-like block is present.
       #
-      # @note module_function: when included, also defines #doc_comment_block_info (instance visibility: private)
-      # @param [Parser::Source::Buffer] buffer
+      # @note module_function: defines #doc_comment_block_info (visibility: private)
+      # @param [Parser::Source::Buffer] buffer source buffer to scan
       # @param [Integer] def_bol_pos beginning-of-line position of the target def
-      # @return [Hash, nil]
+      # @return [Hash<Symbol, Array<String>, Integer, nil>, nil]
       def doc_comment_block_info(buffer, def_bol_pos)
-        src = buffer.source
-        lines = src.lines
-        def_line_idx = src[0...def_bol_pos].count("\n")
-        i = def_line_idx - 1
-
-        # Skip blank lines directly above def
-        i -= 1 while i >= 0 && lines[i].strip.empty?
-
-        # Nearest non-blank line must be a comment
-        return nil unless i >= 0 && lines[i] =~ /^\s*#/
-
-        # Walk upward to include the entire contiguous comment block
-        end_idx = i
-        start_idx = i
-        start_idx -= 1 while start_idx >= 0 && lines[start_idx] =~ /^\s*#/
-        start_idx += 1
+        lines = buffer.source.lines
+        def_line_idx = (buffer.source[0...def_bol_pos] || '').count("\n")
+        block_range = find_comment_block_range(lines, def_line_idx)
+        return nil unless block_range
 
-        # Preserve leading directive-style comments
-        removable_start_idx = start_idx
-        removable_start_idx += 1 while removable_start_idx <= end_idx && preserved_comment_line?(lines[removable_start_idx])
+        start_idx = block_range[:start_idx]
+        end_idx = block_range[:end_idx]
+        preserved_start_idx = find_preserved_start_idx(lines, start_idx, end_idx)
+        return nil unless doc_marker?(lines, preserved_start_idx..end_idx)
 
-        return nil if removable_start_idx > end_idx
-
-        remaining = lines[removable_start_idx..end_idx]
-        return nil unless remaining.any? { |line| doc_marker_line?(line) }
-
-        start_pos = start_idx.positive? ? lines[0...start_idx].join.length : 0
-        doc_start_pos = removable_start_idx.positive? ? lines[0...removable_start_idx].join.length : 0
-        end_pos = lines[0..end_idx].join.length
-
-        {
-          lines: lines[start_idx..end_idx],
-          preserved_lines: lines[start_idx...removable_start_idx],
-          doc_lines: lines[removable_start_idx..end_idx],
-          start_pos: start_pos,
-          doc_start_pos: doc_start_pos,
-          end_pos: end_pos
-        }
+        build_block_info(lines, start_idx, preserved_start_idx, end_idx)
       end
 
       # Compute the removable range for an existing doc-like block above a method.
@@ -97,42 +70,116 @@ module Docscribe
       # Preserved directive lines (such as RuboCop directives or magic comments) are excluded
       # from the returned range.
       #
-      # @note module_function: when included, also defines #comment_block_removal_range (instance visibility: private)
-      # @param [Parser::Source::Buffer] buffer
+      # @note module_function: defines #comment_block_removal_range (visibility: private)
+      # @param [Parser::Source::Buffer] buffer source buffer to scan
       # @param [Integer] def_bol_pos beginning-of-line position of the target def
       # @return [Parser::Source::Range, nil]
       def comment_block_removal_range(buffer, def_bol_pos)
         src = buffer.source
         lines = src.lines
-        def_line_idx = src[0...def_bol_pos].count("\n")
+        def_line_idx = (src[0...def_bol_pos] || '').count("\n")
+        block_range = find_comment_block_range(lines, def_line_idx)
+        return nil unless block_range
+
+        preserved_start_idx = find_preserved_start_idx(lines, block_range[:start_idx], block_range[:end_idx])
+        return nil unless doc_marker?(lines, preserved_start_idx..block_range[:end_idx])
+
+        compute_removal_range(buffer, lines, preserved_start_idx, def_bol_pos)
+      end
+
+      # Find the range of a contiguous comment block directly above a method definition.
+      #
+      # Walks upward from def_line_idx, skipping blank lines, then includes all
+      # contiguous comment lines.
+      #
+      # @note module_function: defines #find_comment_block_range (visibility: private)
+      # @param [Array<String>] lines source code lines
+      # @param [Integer] def_line_idx def line index
+      # @return [Hash<Symbol, Integer>, nil]
+      def find_comment_block_range(lines, def_line_idx)
         i = def_line_idx - 1
 
-        # Skip blank lines directly above def
         i -= 1 while i >= 0 && lines[i].strip.empty?
-
-        # Nearest non-blank line must be a comment to remove anything
         return nil unless i >= 0 && lines[i] =~ /^\s*#/
 
-        # Walk upward to include the entire contiguous comment block
         start_idx = i
         start_idx -= 1 while start_idx >= 0 && lines[start_idx] =~ /^\s*#/
         start_idx += 1
 
-        # Preserve leading directive-style comments (currently: rubocop directives)
-        removable_start_idx = start_idx
-        removable_start_idx += 1 while removable_start_idx <= i && preserved_comment_line?(lines[removable_start_idx])
+        { start_idx: start_idx, end_idx: i }
+      end
 
-        # If the whole block is preserved directives, there is nothing to remove
-        return nil if removable_start_idx > i
+      # Find the first index in a comment block after preserved directive-style lines.
+      #
+      # Preserved lines include RuboCop directives and Ruby magic comments.
+      #
+      # @note module_function: defines #find_preserved_start_idx (visibility: private)
+      # @param [Array<String>] lines source code lines
+      # @param [Integer] start_idx block start index
+      # @param [Integer] end_idx block end index
+      # @return [Integer]
+      def find_preserved_start_idx(lines, start_idx, end_idx)
+        idx = start_idx
+        idx += 1 while idx <= end_idx && preserved_comment_line?(lines[idx])
+        idx
+      end
 
-        # SAFETY: only remove if the remaining block looks like documentation
-        remaining = lines[removable_start_idx..i]
-        return nil unless remaining.any? { |line| doc_marker_line?(line) }
+      # Whether a comment block range contains documentation markers.
+      #
+      # @note module_function: defines #doc_marker? (visibility: private)
+      # @param [Array<String>] lines source code lines
+      # @param [Range<Integer>] range line index range
+      # @return [Boolean]
+      def doc_marker?(lines, range)
+        (lines[range] || []).any? { |line| doc_marker_line?(line) }
+      end
 
-        start_pos = removable_start_idx.positive? ? lines[0...removable_start_idx].join.length : 0
+      # Build block info hash from computed line ranges.
+      #
+      # @note module_function: defines #build_block_info (visibility: private)
+      # @param [Array<String>] lines source code lines
+      # @param [Integer] start_idx block start index
+      # @param [Integer] preserved_start_idx preserved start index
+      # @param [Integer] end_idx block end index
+      # @return [Hash<Symbol, Array<String>, Integer, nil>]
+      def build_block_info(lines, start_idx, preserved_start_idx, end_idx)
+        positions = compute_positions(lines, start_idx, preserved_start_idx, end_idx)
+        {
+          lines: lines[start_idx..end_idx],
+          preserved_lines: lines[start_idx...preserved_start_idx],
+          doc_lines: lines[preserved_start_idx..end_idx],
+          **positions
+        }
+      end
+
+      # Compute the removal range for preserved start position.
+      #
+      # @note module_function: defines #compute_removal_range (visibility: private)
+      # @param [Parser::Source::Buffer] buffer source buffer for position
+      # @param [Array<String>] lines source code lines
+      # @param [Integer] preserved_start_idx preserved start index
+      # @param [Integer] def_bol_pos beginning-of-line position of the target def
+      # @return [Parser::Source::Range]
+      def compute_removal_range(buffer, lines, preserved_start_idx, def_bol_pos)
+        start_pos = preserved_start_idx.positive? ? (lines[0...preserved_start_idx] || []).join.length : 0
         Parser::Source::Range.new(buffer, start_pos, def_bol_pos)
       end
 
+      # Compute source positions for a comment block.
+      #
+      # @note module_function: defines #compute_positions (visibility: private)
+      # @param [Array<String>] lines source code lines
+      # @param [Integer] start_idx block start index
+      # @param [Integer] doc_start_idx doc content start index
+      # @param [Integer] end_pos_idx block end position index
+      # @return [Hash<Symbol, Integer>]
+      def compute_positions(lines, start_idx, doc_start_idx, end_pos_idx)
+        start_pos = start_idx.positive? ? (lines[0...start_idx] || []).join.length : 0
+        doc_start_pos = doc_start_idx.positive? ? (lines[0...doc_start_idx] || []).join.length : 0
+        end_pos = (lines[0..end_pos_idx] || []).join.length
+        { start_pos: start_pos, doc_start_pos: doc_start_pos, end_pos: end_pos }
+      end
+
       # Whether a comment line should be preserved during aggressive replacement.
       #
       # Preserved lines include:
@@ -140,8 +187,8 @@ module Docscribe
       # - Ruby magic comments
       # - tool directives such as `:nocov:` / `:stopdoc:`
       #
-      # @note module_function: when included, also defines #preserved_comment_line? (instance visibility: private)
-      # @param [String] line
+      # @note module_function: defines #preserved_comment_line? (visibility: private)
+      # @param [String] line comment line to check
       # @return [Boolean]
       def preserved_comment_line?(line)
         # RuboCop directives
@@ -166,8 +213,8 @@ module Docscribe
       # - Docscribe header lines
       # - YARD tags/directives beginning with `@`
       #
-      # @note module_function: when included, also defines #doc_marker_line? (instance visibility: private)
-      # @param [String] line
+      # @note module_function: defines #doc_marker_line? (visibility: private)
+      # @param [String] line comment line to check
       # @return [Boolean]
       def doc_marker_line?(line)
         # Docscribe header line:
@@ -191,14 +238,14 @@ module Docscribe
       #
       # This helper is retained for compatibility/legacy behavior checks.
       #
-      # @note module_function: when included, also defines #already_has_doc_immediately_above? (instance visibility: private)
-      # @param [Parser::Source::Buffer] buffer
-      # @param [Integer] insert_pos
+      # @note module_function: defines #already_has_doc_immediately_above? (visibility: private)
+      # @param [Parser::Source::Buffer] buffer source buffer to check
+      # @param [Integer] insert_pos insertion position
       # @return [Boolean]
       def already_has_doc_immediately_above?(buffer, insert_pos)
         src = buffer.source
         lines = src.lines
-        current_line_index = src[0...insert_pos].count("\n")
+        current_line_index = (src[0...insert_pos] || '').count("\n")
         i = current_line_index - 1
         i -= 1 while i >= 0 && lines[i].strip.empty?
         return false if i.negative?
@@ -210,10 +257,11 @@ module Docscribe
       #
       # Tabs and spaces are preserved exactly.
       #
-      # @note module_function: when included, also defines #line_indent (instance visibility: private)
-      # @param [Parser::AST::Node] node
+      # @note module_function: defines #line_indent (visibility: private)
+      # @param [Parser::AST::Node] node target AST node
       # @raise [StandardError]
-      # @return [String]
+      # @return [String] if StandardError
+      # @return [String] if StandardError
       def line_indent(node)
         line = node.loc.expression.source_line
         return '' unless line

data/lib/docscribe/inline_rewriter/tag_sorter.rb

@@ -11,33 +11,30 @@ module Docscribe
     module TagSorter
       module_function
 
-      # One sortable top-level tag entry plus its continuation lines.
       # @!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] param_name
-      #   @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] index
-      #   @return [Object]
-      #   @param [Object] value
+      #   @return [Integer]
+      #   @param [Integer] value
       Entry = Struct.new(:tag, :lines, :param_name, :option_owner, :index, keyword_init: true)
 
-      # Sort contiguous top-level tag runs according to configured tag order.
+      # Sort
       #
-      # Non-tag content is preserved as-is and acts as a sort boundary.
-      #
-      # @note module_function: when included, also defines #sort (instance visibility: private)
+      # @note module_function: defines #sort (visibility: private)
       # @param [Array<String>] lines comment block lines
       # @param [Array<String>] tag_order configured tag order
       # @return [Array<String>]
@@ -47,50 +44,69 @@ module Docscribe
         segments.flat_map { |seg| sort_segment(seg, priority: priority) }
       end
 
-      # Build a tag priority map from configured tag order.
+      # Build priority
       #
-      # @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 tag order
+      # @return [Hash<String, Integer>]
       def build_priority(tag_order)
         Array(tag_order).map { |t| t.to_s.sub(/\A@/, '') }
                         .each_with_index
                         .to_h
       end
 
-      # Parse lines into sortable tag-run segments and non-sortable segments.
+      # Parse segments
       #
-      # @note module_function: when included, also defines #parse_segments (instance visibility: private)
-      # @param [Array<String>] lines
-      # @return [Array<Hash>]
+      # @note module_function: defines #parse_segments (visibility: private)
+      # @param [Array<String>] lines comment block lines
+      # @return [Array<Hash<Symbol, Object>>]
       def parse_segments(lines)
-        segments = []
+        segments = [] #: Array[untyped]
         i = 0
 
-        while i < lines.length
-          line = lines[i]
+        i = advance_parse(lines, i, segments) while i < lines.length
+
+        segments
+      end
 
-          if top_level_tag_line?(line)
-            entries = []
-            while i < lines.length && top_level_tag_line?(lines[i])
-              entry, i = consume_entry(lines, i)
-              entries << entry
-            end
-            segments << { type: :tag_run, entries: entries }
-          else
-            segments << { type: :other, lines: [line] }
-            i += 1
-          end
+      # Advance parse
+      #
+      # @note module_function: defines #advance_parse (visibility: private)
+      # @param [Array<String>] lines comment block lines
+      # @param [Integer] idx current parse index
+      # @param [Array<Hash<Symbol, Object>>] segments accumulated parsed segments
+      # @return [Integer] new index after processing
+      def advance_parse(lines, idx, segments)
+        if top_level_tag_line?(lines[idx])
+          consume_tag_run(lines, idx, segments)
+        else
+          segments << { type: :other, lines: [lines[idx]] }
+          idx + 1
         end
+      end
 
-        segments
+      # Consume tag run
+      #
+      # @note module_function: defines #consume_tag_run (visibility: private)
+      # @param [Array<String>] lines comment block lines
+      # @param [Integer] idx current index
+      # @param [Array<Hash<Symbol, Object>>] segments accumulated segments
+      # @return [Integer] new index after consuming the run
+      def consume_tag_run(lines, idx, segments)
+        entries = [] #: Array[untyped]
+        while idx < lines.length && top_level_tag_line?(lines[idx])
+          entry, idx = consume_entry(lines, idx)
+          entries << entry
+        end
+        segments << { type: :tag_run, entries: entries }
+        idx
       end
 
-      # Sort one parsed segment if it is a tag run.
+      # Sort segment
       #
-      # @note module_function: when included, also defines #sort_segment (instance visibility: private)
-      # @param [Hash] segment
-      # @param [Hash{String=>Integer}] priority
+      # @note module_function: defines #sort_segment (visibility: private)
+      # @param [Hash<Symbol, Object>] segment parsed comment segment
+      # @param [Hash<String, Integer>] priority tag priority map
       # @return [Array<String>]
       def sort_segment(segment, priority:)
         return segment[:lines] unless segment[:type] == :tag_run
@@ -104,125 +120,167 @@ module Docscribe
           .flat_map(&:lines)
       end
 
-      # Compute sort priority for a grouped tag entry.
+      # Group priority
       #
-      # @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::TagSorter::Entry>] group entry group array
+      # @param [Hash<String, Integer>] priority tag priority map
       # @return [Integer]
       def group_priority(group, priority)
         first = group.first
         priority.fetch(first.tag, priority.length)
       end
 
-      # Consume one top-level tag entry and its continuation lines.
+      # Consume entry
       #
-      # @note module_function: when included, also defines #consume_entry (instance visibility: private)
-      # @param [Array<String>] lines
-      # @param [Integer] start_idx
-      # @return [Array<(Entry, Integer)>]
+      # @note module_function: defines #consume_entry (visibility: private)
+      # @param [Array<String>] lines comment block lines
+      # @param [Integer] start_idx original index of the first line
+      # @return [(Docscribe::InlineRewriter::TagSorter::Entry, Integer)]
       def consume_entry(lines, start_idx)
         first = lines[start_idx]
-        tag = extract_tag_name(first)
-        entry_lines = [first]
-        i = start_idx + 1
-
-        while i < lines.length
-          line = lines[i]
+        tag = extract_tag_name(first) || ''
+        entry_lines = collect_continuation_lines(lines, start_idx + 1)
+        i = entry_lines.length + start_idx
 
-          break if top_level_tag_line?(line)
-          break if blank_comment_line?(line)
-          break unless comment_line?(line)
+        entry = build_entry(tag, entry_lines, first, start_idx)
 
-          entry_lines << line
-          i += 1
-        end
+        [entry, i]
+      end
 
-        entry = Entry.new(
+      # Build entry
+      #
+      # @note module_function: defines #build_entry (visibility: private)
+      # @param [String] tag the extracted tag name
+      # @param [Array<String>] entry_lines all lines belonging to this entry
+      # @param [String] first the first (tag) line
+      # @param [Integer] start_idx original index of the first line
+      # @return [Docscribe::InlineRewriter::TagSorter::Entry]
+      def build_entry(tag, entry_lines, first, start_idx)
+        Entry.new(
           tag: tag,
           lines: entry_lines,
           param_name: extract_param_name(first),
           option_owner: extract_option_owner(first),
           index: start_idx
         )
+      end
 
-        [entry, i]
+      # Collect continuation lines
+      #
+      # @note module_function: defines #collect_continuation_lines (visibility: private)
+      # @param [Array<String>] lines comment block lines
+      # @param [Integer] start_idx original index of the first line
+      # @return [Array<String>]
+      def collect_continuation_lines(lines, start_idx)
+        result = [] #: Array[String]
+        i = start_idx
+
+        while i < lines.length
+          line = lines[i]
+          break if top_level_tag_line?(line) || blank_comment_line?(line) || !comment_line?(line)
+
+          result << line
+          i += 1
+        end
+
+        result
       end
 
-      # Group entries so `@option` tags remain attached to their owning `@param`.
+      # Group entries
       #
-      # @note module_function: when included, also defines #group_entries (instance visibility: private)
-      # @param [Array<Entry>] entries
-      # @return [Array<Array<Entry>>]
+      # @note module_function: defines #group_entries (visibility: private)
+      # @param [Array<Docscribe::InlineRewriter::TagSorter::Entry>] entries parsed tag entries
+      # @return [Array<Array<Docscribe::InlineRewriter::TagSorter::Entry>>]
       def group_entries(entries)
-        groups = []
+        groups = [] #: Array[untyped]
         i = 0
 
         while i < entries.length
-          entry = entries[i]
-
-          if entry.tag == 'param'
-            group = [entry]
-            i += 1
-
-            while i < entries.length &&
-                  entries[i].tag == 'option' &&
-                  entries[i].option_owner &&
-                  entries[i].option_owner == entry.param_name
-              group << entries[i]
-              i += 1
-            end
-
-            groups << group
-          else
-            groups << [entry]
-            i += 1
-          end
+          groups << group_entry(entries, i)
+          i += 1
         end
 
         groups
       end
 
-      # Whether a line begins a top-level tag entry.
+      # Group entry
+      #
+      # @note module_function: defines #group_entry (visibility: private)
+      # @param [Array<Docscribe::InlineRewriter::TagSorter::Entry>] entries parsed tag entries
+      # @param [Integer] idx index of the entry to group
+      # @return [Array<Docscribe::InlineRewriter::TagSorter::Entry>] the entry group
+      def group_entry(entries, idx)
+        entry = entries[idx]
+        if entry.tag == 'param'
+          [entry] + collect_option_entries(entries, idx + 1, entry.param_name || '')
+        else
+          [entry]
+        end
+      end
+
+      # Collect option entries
+      #
+      # @note module_function: defines #collect_option_entries (visibility: private)
+      # @param [Array<Docscribe::InlineRewriter::TagSorter::Entry>] entries parsed tag entries
+      # @param [Integer] start_idx original index of the first line
+      # @param [String] param_name parent param name
+      # @return [Array<Docscribe::InlineRewriter::TagSorter::Entry>]
+      def collect_option_entries(entries, start_idx, param_name)
+        result = [] #: Array[untyped]
+        i = start_idx
+
+        while i < entries.length &&
+              entries[i].tag == 'option' &&
+              entries[i].option_owner &&
+              entries[i].option_owner == param_name
+          result << entries[i]
+          i += 1
+        end
+
+        result
+      end
+
+      # Top level tag line
       #
-      # @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 comment line to check
       # @return [Boolean]
       def top_level_tag_line?(line)
         !!(line =~ /^\s*#\s*@\w+/)
       end
 
-      # Whether a line is any comment line.
+      # 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 comment line to check
       # @return [Boolean]
       def comment_line?(line)
         !!(line =~ /^\s*#/)
       end
 
-      # Whether a line is a blank comment separator.
+      # Blank comment line
       #
-      # @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 comment line to check
       # @return [Boolean]
       def blank_comment_line?(line)
         !!(line =~ /^\s*#\s*$/)
       end
 
-      # Extract tag name from a top-level tag line without the leading `@`.
+      # Extract tag name
       #
-      # @note module_function: when included, also defines #extract_tag_name (instance visibility: private)
-      # @param [String] line
+      # @note module_function: defines #extract_tag_name (visibility: private)
+      # @param [String] line comment line to parse
       # @return [String, nil]
       def extract_tag_name(line)
         line[/^\s*#\s*@(\w+)/, 1]
       end
 
-      # Extract parameter name from a `@param` line.
+      # Extract param name
       #
-      # @note module_function: when included, also defines #extract_param_name (instance visibility: private)
-      # @param [String] line
+      # @note module_function: defines #extract_param_name (visibility: private)
+      # @param [String] line param tag line to parse
       # @return [String, nil]
       def extract_param_name(line)
         return Regexp.last_match(1) if line =~ /^\s*#\s*@param\b\s+\[[^\]]+\]\s+(\S+)/
@@ -231,10 +289,10 @@ module Docscribe
         nil
       end
 
-      # Extract owning options-hash param name from an `@option` line.
+      # Extract option owner
       #
-      # @note module_function: when included, also defines #extract_option_owner (instance visibility: private)
-      # @param [String] line
+      # @note module_function: defines #extract_option_owner (visibility: private)
+      # @param [String] line option tag line to parse
       # @return [String, nil]
       def extract_option_owner(line)
         line[/^\s*#\s*@option\b\s+(\S+)/, 1]