docscribe 1.4.1 → 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,37 +55,28 @@ 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 Param documentation.
+      # @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)
         missing_entries = parse_generated(missing_lines, tag_order: tag_order)
-
-        filter_param_names = filter_existing[:param_names] || []
-        filter_return = !!filter_existing[:return]
-
-        existing_entries = existing_entries.reject do |e|
-          (e.kind == :tag && e.tag == 'param' && filter_param_names.include?(e.subject)) ||
-            (e.kind == :tag && e.tag == 'return' && filter_return)
-        end
-
+        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
 
       # 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
@@ -98,75 +84,154 @@ module Docscribe
         end
       end
 
+      # Remove existing entries matching the filter criteria (param names or return tag).
+      #
+      # @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]
+        entries.reject do |entry|
+          filter_param_entry?(entry, filter_param_names) || filter_return_entry?(entry, filter_return)
+        end
+      end
+
+      # Check whether an entry is a @param tag whose name is in the filter list.
+      #
+      # @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)
+        entry.kind == :tag && entry.tag == 'param' && param_names.include?(entry.subject)
+      end
+
+      # Check whether an entry is a @return tag that should be filtered.
+      #
+      # @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)
+        entry.kind == :tag && entry.tag == 'return' && filter_return
+      end
+
       # 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.
       #
-      # @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)
-        entries = []
-        i = 0
-        index = 0
-
-        while i < lines.length
-          line = lines[i]
-
-          if sortable_top_level_tag_line?(line, sortable_tags)
-            entry, i = consume_tag_entry(lines, i, index: index, sortable_tags: sortable_tags)
-            entries << entry
-          else
-            entries << Entry.new(
-              kind: :other,
-              lines: [line],
-              generated: false,
-              index: index
-            )
-            i += 1
-          end
+        parse_lines(lines, sortable_tags, entries: [], index: 0)
+      end
 
+      # Iterate through all lines and parse each one into a structured entry.
+      #
+      # @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<Docscribe::InlineRewriter::DocBlock::Entry>] entries accumulated parsed entries
+      # @param [Integer] index stable ordering index for entries
+      # @return [Array<Docscribe::InlineRewriter::DocBlock::Entry>]
+      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 a single line as a sortable tag entry or non-tag content.
+      #
+      # @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<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)
+        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
+
+      # Create an :other entry for a non-tag line (prose, blank separators, etc.).
+      #
+      # @note module_function: defines #build_other_entry (visibility: private)
+      # @param [String] line the comment line
+      # @param [Integer] index stable ordering index
+      # @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 = []
+        out = [] #: Array[untyped]
         priority = build_priority(tag_order)
-        i = 0
-
-        while i < entries.length
-          if entries[i].kind == :tag
-            run = []
-            while i < entries.length && entries[i].kind == :tag
-              run << entries[i]
-              i += 1
-            end
+        sort_loop(entries, out, priority)
+        out
+      end
+
+      # Iterate entries, sorting contiguous tag runs while preserving non-tag boundaries.
+      #
+      # @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
+
+        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[i]
-            i += 1
+            out << entries[idx]
+            idx += 1
           end
         end
+      end
 
-        out
+      # Collect a contiguous run of :tag entries starting at idx.
+      #
+      # @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<Docscribe::InlineRewriter::DocBlock::Entry>, Integer)]
+      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
 
       # 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)
@@ -174,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)
 
@@ -190,43 +255,72 @@ 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 = []
-        i = 0
-
-        while i < entries.length
-          entry = entries[i]
+        groups = [] #: Array[untyped]
+        group_entries_loop(entries, groups)
+        groups
+      end
 
-          if entry.tag == 'param'
-            group = [entry]
-            i += 1
+      # Iterate entries to build sorted groups, attaching @option entries to their @param.
+      #
+      # @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
+        idx = group_one_entry(entries, idx, groups) while idx < entries.length
+      end
 
-            while i < entries.length &&
-                  entries[i].tag == 'option' &&
-                  entries[i].option_owner &&
-                  entries[i].option_owner == entry.subject
-              group << entries[i]
-              i += 1
-            end
+      # Group a single entry, creating a param group with @option children if applicable.
+      #
+      # @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<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]
+        if entry.tag == 'param'
+          group = build_param_group(entries, idx, entry)
+          groups << group
+          idx + group.size
+        else
+          groups << [entry]
+          idx + 1
+        end
+      end
 
-            groups << group
-          else
-            groups << [entry]
-            i += 1
-          end
+      # Build a group starting with a @param entry and including its following @option 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 [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
+
+        while idx < entries.length &&
+              entries[idx].tag == 'option' &&
+              entries[idx].option_owner &&
+              entries[idx].option_owner == entry.subject
+          group << entries[idx]
+          idx += 1
         end
 
-        groups
+        group
       end
 
       # 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)
@@ -234,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@/, '') }
@@ -255,30 +349,76 @@ 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)
+        [entry, i]
+      end
 
-        entry_lines = [first]
-        i = start_idx + 1
+      # Collect the first tag line and all continuation lines belonging to the same entry.
+      #
+      # @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
+      # @param [Array<String>] sortable_tags tag names treated as sortable
+      # @return [Array<String>] all lines belonging to this entry
+      def collect_continuation_lines(lines, start_idx, first, sortable_tags)
+        result = [first]
+        add_continuation_lines(lines, start_idx, result, sortable_tags)
+        result
+      end
 
+      # Append continuation lines to the result array until a non-continuation line is found.
+      #
+      # @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
+      # @param [Array<String>] sortable_tags tag names treated as sortable
+      # @return [void]
+      def add_continuation_lines(lines, start_idx, result, sortable_tags)
+        i = start_idx
         while i < lines.length
           line = lines[i]
-          break if sortable_top_level_tag_line?(line, sortable_tags)
-          break if blank_comment_line?(line)
-          break unless continuation_comment_line?(line)
+          break unless continuation_candidate?(line, sortable_tags)
 
-          entry_lines << line
+          result << line
           i += 1
         end
+      end
 
-        entry = Entry.new(
+      # Check whether a line can serve as a continuation of the current tag entry.
+      #
+      # @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]
+      def continuation_candidate?(line, sortable_tags)
+        !sortable_top_level_tag_line?(line, sortable_tags) &&
+          !blank_comment_line?(line) &&
+          continuation_comment_line?(line)
+      end
+
+      # Build a tag Entry struct with metadata from the parsed tag line and continuation lines.
+      #
+      # @note module_function: defines #build_tag_entry (visibility: private)
+      # @param [String] first the first (tag) line
+      # @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 [Docscribe::InlineRewriter::DocBlock::Entry]
+      def build_tag_entry(first, tag, entry_lines, index)
+        Entry.new(
           kind: :tag,
           tag: tag,
           lines: entry_lines,
@@ -287,18 +427,16 @@ module Docscribe
           generated: false,
           index: index
         )
-
-        [entry, i]
       end
 
       # Extract the grouping subject for a sortable tag.
       #
       # 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'
@@ -312,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)
@@ -345,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+/)
@@ -363,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*#/)
@@ -372,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*$/)
@@ -381,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/)