yard-lint 1.6.1 → 1.8.0

data/lib/yard/lint/validators/documentation/underfilled_lines/validator.rb

@@ -0,0 +1,266 @@
+# frozen_string_literal: true
+
+module Yard
+  module Lint
+    module Validators
+      module Documentation
+        module UnderfilledLines
+          # Detects documentation prose that wraps before using the available line width.
+          #
+          # Uses YARD's `docstring.line_range` to locate the exact source lines belonging
+          # to the docstring block (mirroring {LineLength}), classifies each line as prose
+          # or structural, groups contiguous prose into paragraphs, and reports a
+          # paragraph when greedily re-wrapping it at `MaxLength` would use fewer lines.
+          class Validator < Validators::Base
+            in_process visibility: :all
+
+            # Characters that may trail a sentence boundary char without changing the
+            # fact that the line ends a clause (closing bracket/quote/backtick).
+            TRAILING_CLOSERS = /[)\]"'`]+\z/
+
+            # Execute query for a single object during in-process execution.
+            # @param object [YARD::CodeObjects::Base] the code object to query
+            # @param collector [Executor::ResultCollector] collector for output
+            # @return [void]
+            def in_process_query(object, collector)
+              return unless object.file && File.exist?(object.file)
+              return if object.docstring.all.empty?
+
+              line_range = object.docstring.line_range
+              return unless line_range
+              return if duplicate_docstring?(object)
+
+              max_length = config_or_default('MaxLength').to_i
+              min_trailing = config_or_default('MinTrailingSpace').to_i
+              min_lines = [config_or_default('MinParagraphLines').to_i, 2].max
+              boundary = Array(config_or_default('SentenceEndChars'))
+              skip_non_ascii = config_or_default('SkipNonAscii')
+
+              source_lines = cached_lines(object.file)
+              classified = classify_lines(line_range, source_lines, skip_non_ascii)
+
+              violations = []
+              group_paragraphs(classified).each do |paragraph|
+                next if paragraph.size < min_lines
+                next if ventilated?(paragraph, boundary)
+
+                actual = paragraph.size
+                reflowed = reflow_count(paragraph, max_length)
+                next unless reflowed < actual
+
+                widest = paragraph[0..-2].map { |line| line[:length] }.max
+                next if (max_length - widest) < min_trailing
+
+                violations << "#{paragraph.first[:line_no]}:#{actual}:#{reflowed}:#{widest}"
+              end
+
+              return if violations.empty?
+
+              collector.puts "#{object.file}:#{object.line}: #{object.title}"
+              collector.puts "#{max_length}|#{violations.join('|')}"
+            end
+
+            private
+
+            # Classify each source line in the docstring range. Plain-prose lines become
+            # hashes; everything else (blank lines, tags, code, markdown structure) is a
+            # `:break` marker that separates paragraphs.
+            # @param line_range [Range] absolute source line numbers of the docstring
+            # @param source_lines [Array<String>] raw lines of the source file
+            # @param skip_non_ascii [Boolean] treat non-ASCII lines as structural
+            # @return [Array<Hash, Symbol>] prose hashes interleaved with :break markers
+            def classify_lines(line_range, source_lines, skip_non_ascii)
+              base_indent = base_indent_for(line_range, source_lines)
+              result = []
+              in_fence = false
+              in_tag_region = false
+
+              line_range.each do |line_no|
+                raw = source_lines[line_no - 1].to_s.rstrip
+                marker = raw.match(/\A(\s*#+\s?)(.*)\z/)
+
+                # Not a comment line (e.g. the definition itself, or a block comment body)
+                unless marker
+                  result << :break
+                  in_tag_region = false
+                  next
+                end
+
+                content = marker[2]
+                stripped = content.strip
+
+                # Fenced code block delimiters toggle the fence; the delimiter line and
+                # everything inside it is structural.
+                if stripped.start_with?('```', '~~~')
+                  in_fence = !in_fence
+                  result << :break
+                  next
+                end
+                if in_fence
+                  result << :break
+                  next
+                end
+
+                if stripped.empty?
+                  result << :break
+                  in_tag_region = false
+                  next
+                end
+
+                # A real YARD tag/directive begins at column 0 of the comment content.
+                # It and its indented continuation lines are skipped; only the free-text
+                # description body is checked.
+                if content.start_with?('@')
+                  in_tag_region = true
+                  result << :break
+                  next
+                end
+                if in_tag_region
+                  if content.match?(/\A[ \t]/)
+                    result << :break
+                    next
+                  end
+                  in_tag_region = false
+                end
+
+                # Lines indented past the block's base indentation are code samples,
+                # ASCII diagrams or nested list continuations - not flowing prose.
+                indent = content.length - content.lstrip.length
+                if indent > base_indent || structural_content?(stripped, skip_non_ascii)
+                  result << :break
+                  next
+                end
+
+                result << {
+                  line_no: line_no,
+                  prefix_width: raw.length - stripped.length,
+                  content: stripped,
+                  length: raw.length
+                }
+              end
+
+              result
+            end
+
+            # The smallest content indentation among non-empty comment lines in the
+            # range. Flowing prose sits at this base; anything deeper is treated as a
+            # nested, code or diagram line.
+            # @param line_range [Range] absolute source line numbers of the docstring
+            # @param source_lines [Array<String>] raw lines of the source file
+            # @return [Integer] base indentation in columns (0 for normal `# ` comments)
+            def base_indent_for(line_range, source_lines)
+              indents = []
+              line_range.each do |line_no|
+                raw = source_lines[line_no - 1].to_s.rstrip
+                marker = raw.match(/\A(\s*#+\s?)(.*)\z/)
+                next unless marker
+
+                content = marker[2]
+                next if content.strip.empty?
+
+                indents << (content.length - content.lstrip.length)
+              end
+              indents.min || 0
+            end
+
+            # Whether a prose-looking comment line is actually structural and must not
+            # take part in reflow (markdown, code, diagrams, RDoc directives, ...).
+            # @param stripped [String] comment content, stripped of the marker and whitespace
+            # @param skip_non_ascii [Boolean] treat non-ASCII content as structural
+            # @return [Boolean]
+            def structural_content?(stripped, skip_non_ascii)
+              return true if skip_non_ascii && !stripped.ascii_only?
+              # Markdown heading, blockquote
+              return true if stripped.start_with?('#', '>')
+              # Table row
+              return true if stripped.include?('|')
+              # List items (bulleted or ordered)
+              return true if stripped.match?(/\A[-*+]\s/)
+              return true if stripped.match?(/\A\d+[.)]\s/)
+              # Thematic break (---, ***, ___)
+              return true if stripped.match?(/\A([-*_])\1\1+\z/)
+              # RDoc directives
+              return true if stripped.match?(/\A:\w+:/)
+              return true if stripped.end_with?(':nodoc:', ':doc:')
+              # Intentional hard break / hyphenation
+              return true if stripped.end_with?('-')
+              # Column alignment (2+ internal spaces) or box-drawing diagrams
+              return true if stripped.match?(/\S {2,}\S/)
+              return true if stripped.match?(/[─-╿▀-▟]/)
+
+              false
+            end
+
+            # Group the classified entries into paragraphs: maximal runs of contiguous
+            # prose lines sharing the same comment-marker indentation.
+            # @param classified [Array<Hash, Symbol>] output of {#classify_lines}
+            # @return [Array<Array<Hash>>] paragraphs, each an array of prose line hashes
+            def group_paragraphs(classified)
+              paragraphs = []
+              current = []
+
+              flush = lambda do
+                paragraphs << current unless current.empty?
+                current = []
+              end
+
+              classified.each do |entry|
+                if entry == :break
+                  flush.call
+                elsif current.empty? || current.last[:prefix_width] == entry[:prefix_width]
+                  current << entry
+                else
+                  flush.call
+                  current << entry
+                end
+              end
+              flush.call
+
+              paragraphs
+            end
+
+            # Whether a paragraph is deliberately broken one sentence/clause per line.
+            # True when every non-final line ends at a sentence boundary character.
+            # @param paragraph [Array<Hash>] prose line hashes
+            # @param boundary [Array<String>] sentence-ending characters
+            # @return [Boolean]
+            def ventilated?(paragraph, boundary)
+              return false if boundary.empty?
+
+              paragraph[0..-2].all? do |line|
+                last = line[:content].sub(TRAILING_CLOSERS, '')[-1]
+                last && boundary.include?(last)
+              end
+            end
+
+            # Number of lines the paragraph's words occupy when greedily wrapped at
+            # `max_length`, using the paragraph's comment-marker prefix on every line.
+            # A word that does not fit starts a new line, so breaks forced by an
+            # unbreakable long token (URL, namespaced constant) are reproduced and do
+            # not count as savings.
+            # @param paragraph [Array<Hash>] prose line hashes
+            # @param max_length [Integer] target width
+            # @return [Integer] number of wrapped lines
+            def reflow_count(paragraph, max_length)
+              prefix_width = paragraph.first[:prefix_width]
+              words = paragraph.flat_map { |line| line[:content].split }
+              return paragraph.size if words.empty?
+
+              lines = 1
+              current = prefix_width + words.first.length
+              words.drop(1).each do |word|
+                if current + 1 + word.length <= max_length
+                  current += 1 + word.length
+                else
+                  lines += 1
+                  current = prefix_width + word.length
+                end
+              end
+              lines
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/yard/lint/validators/documentation/underfilled_lines.rb

@@ -0,0 +1,74 @@
+# frozen_string_literal: true
+
+module Yard
+  module Lint
+    module Validators
+      module Documentation
+        # UnderfilledLines validator
+        #
+        # The inverse of {LineLength}: instead of flagging documentation lines that are
+        # too *long*, it flags documentation prose paragraphs that wrap **too early** -
+        # text that uses only a fraction of the available width and spills onto extra
+        # lines, wasting vertical space. This pattern is common in AI-generated docs.
+        #
+        # Only the free-text description body is checked. YARD tags (`@param`, `@return`,
+        # `@example`, ...), fenced and indented code, lists, tables, headings,
+        # blockquotes and non-ASCII text are left untouched. A paragraph is reported
+        # only when *all* of these hold, so ambiguous cases are never flagged:
+        #
+        # * greedily re-wrapping its words at `MaxLength` would genuinely use fewer lines;
+        # * the unused space on its widest line is at least `MinTrailingSpace` columns;
+        # * it is not deliberately broken one sentence/clause per line (every non-final
+        #   line ending at a `SentenceEndChars` boundary is treated as an intentional
+        #   semantic line break and skipped).
+        #
+        # Disabled by default - this is a stylistic, opinionated check. Enable it to
+        # tighten draft or AI-written documentation.
+        #
+        # @example Bad - prose wraps at ~55 columns when 120 are available
+        #   # Processes the incoming payload and returns a normalized
+        #   # hash that downstream consumers can rely on for routing.
+        #   def process(payload)
+        #   end
+        #
+        # @example Good - prose fills the available width before wrapping
+        #   # Processes the incoming payload and returns a normalized hash that downstream
+        #   # consumers can rely on for routing.
+        #   def process(payload)
+        #   end
+        #
+        # @example Good - semantic line breaks (one sentence per line) are never flagged
+        #   # Validates the input.
+        #   # Normalizes the casing.
+        #   # Persists the record.
+        #   def call
+        #   end
+        #
+        # ## Configuration
+        #
+        # To enable with custom settings:
+        #
+        #     Documentation/UnderfilledLines:
+        #       Enabled: true
+        #       MaxLength: 120
+        #       MinTrailingSpace: 20
+        #
+        # ## Reliability
+        #
+        # Unlike {LineLength} - which measures an objective property (characters over a
+        # limit) - "this line should have been longer" is a stylistic judgement. The
+        # validator is deliberately conservative and biased toward silence: it would
+        # rather miss a case than emit a false positive. Projects that use semantic line
+        # breaks (one sentence or clause per line, see https://sembr.org) should leave it
+        # off, or add `,` to `SentenceEndChars`.
+        #
+        # To disable:
+        #
+        #     Documentation/UnderfilledLines:
+        #       Enabled: false
+        module UnderfilledLines
+        end
+      end
+    end
+  end
+end

data/lib/yard/lint/validators/documentation/undocumented_method_arguments/config.rb

@@ -12,7 +12,16 @@ module Yard
               'Enabled' => true,
               'Severity' => 'warning',
               'AllowedParentClasses' => [],
-              'AllowedMethods' => []
+              'AllowedMethods' => [],
+              # Match each parameter to a @param tag by name (default). Catches a
+              # misnamed @param (e.g. `@param wrong` for `def push(item)`) that a
+              # count-only check would accept. Set to false to fall back to the
+              # lenient count-only comparison.
+              'CheckParameterNames' => true,
+              # Opt-in: skip methods with no documentation at all and let
+              # Documentation/UndocumentedObjects report them, avoiding a second
+              # offense for the same fully-undocumented method. Off by default.
+              'SkipFullyUndocumented' => false
             }.freeze
           end
         end

data/lib/yard/lint/validators/documentation/undocumented_method_arguments/parser.rb

@@ -9,9 +9,13 @@ module Yard
           # @example Output format (skip-lint)
           #   /path/to/file.rb:10: Platform::Analysis::Authors#initialize
           class Parser < Parsers::Base
-            # Regex to extract file, line, and method name from yard list output
+            # Regex to extract file, line, and object title from yard list output
             # Format: /path/to/file.rb:10: ClassName#method_name
-            LOCATION_REGEX = /^(.+):(\d+):\s+(.+)[#.](.+)$/
+            LOCATION_REGEX = /^(.+):(\d+):\s+(.+)$/
+            # Splits an object title into namespace and method name on the last
+            # # or . separator. Top-level methods (#foo) have an empty namespace;
+            # titles without a separator (e.g. Foo::Bar, CONST) are kept whole.
+            TITLE_REGEX = /\A(.*)[#.]([^#.]+)\z/
 
             # @param yard_list [String] raw yard list results string
             # @return [Array<Hash>] Array with undocumented method arguments details
@@ -26,8 +30,7 @@ module Yard
                   # Extract: file path, line number, class name, method name
                   file_path = match_data[1]
                   line_number = match_data[2].to_i
-                  class_name = match_data[3]
-                  method_name = match_data[4]
+                  class_name, method_name = split_title(match_data[3])
 
                   {
                     location: file_path,
@@ -37,6 +40,17 @@ module Yard
                   }
                 end
             end
+
+            private
+
+            # Splits a YARD object title into namespace and method name parts
+            # @param title [String] object title (e.g. "Foo#bar", "#bar", "CONST")
+            # @return [Array(String, String)] namespace and method name; for titles
+            #   without a separator both parts are the full title
+            def split_title(title)
+              match = title.match(TITLE_REGEX)
+              match ? [match[1], match[2]] : [title, title]
+            end
           end
         end
       end

data/lib/yard/lint/validators/documentation/undocumented_method_arguments/validator.rb

@@ -27,14 +27,48 @@ module Yard
               # doesn't need explicit @param documentation, matching attr_accessor behavior
               return if object.is_attribute?
 
-              # Check if parameters count exceeds @param tags count
-              param_count = object.parameters.size
-              param_tags_count = object.tags(:param).size
+              # Splat (*args, **opts) and block (&block) parameters are excluded -
+              # blocks are documented with @yield rather than @param, matching the
+              # arity convention used everywhere else in the gem (e.g. method_allowed?).
+              params = object.parameters.reject { |p| p[0].to_s.start_with?('*', '&') }
+              return if params.empty?
 
-              return unless param_count > param_tags_count
+              # Opt-in: defer fully-undocumented methods to
+              # Documentation/UndocumentedObjects instead of reporting them here too.
+              return if config_or_default('SkipFullyUndocumented') && object.docstring.blank?
+
+              return unless arguments_missing_docs?(object, params)
 
               collector.puts "#{object.file}:#{object.line}: #{object.title}"
             end
+
+            private
+
+            # Decide whether a method's parameters are under-documented.
+            # @param object [YARD::CodeObjects::MethodObject] the method to check
+            # @param params [Array<Array>] non-splat/block parameters
+            # @return [Boolean] true if documentation is missing
+            def arguments_missing_docs?(object, params)
+              # Tags nested inside @overload blocks live on the overload's own
+              # docstring, so all_typed_tags collects those @param tags too.
+              param_tags = all_typed_tags(object.docstring, %w[param])
+
+              if config_or_default('CheckParameterNames')
+                documented = param_tags.map { |tag| normalize_param_name(tag.name) }
+                params.any? { |param| !documented.include?(normalize_param_name(param[0])) }
+              else
+                params.size > param_tags.size
+              end
+            end
+
+            # Normalize a parameter or @param name for comparison by stripping a
+            # trailing `:` - keyword parameters appear as `name:` in
+            # object.parameters but `name` in @param tag names.
+            # @param name [String, Symbol, nil] the raw name
+            # @return [String] the normalized name
+            def normalize_param_name(name)
+              name.to_s.sub(/:\z/, '')
+            end
           end
         end
       end

data/lib/yard/lint/validators/documentation/undocumented_objects/parser.rb

@@ -62,6 +62,12 @@ module Yard
             # @param excluded_methods [Array<String>] list of exclusion patterns
             # @return [Boolean] true if method should be excluded
             def method_excluded?(element, arity, excluded_methods)
+              # ExcludedMethods only applies to methods. A class, module, or
+              # constant element has no #/. separator, so never derive a
+              # "method name" from it - otherwise a pattern like /cache/ would
+              # silently suppress the offense for a class such as Memcached.
+              return false unless element.match?(/[#.]/)
+
               # Extract method name from element (e.g., "Foo::Bar#baz" -> "baz")
               method_name = element.split(/[#.]/).last
               return false unless method_name

data/lib/yard/lint/validators/documentation/undocumented_options/validator.rb

@@ -32,6 +32,11 @@ module Yard
 
               return unless has_options_param
 
+              # A named (non-splat) parameter documented with a concrete
+              # non-Hash type (via its param tag) is not an options hash, so it
+              # does not need option tags.
+              return if options_param_documented_as_non_hash?(object)
+
               # Check if @option tags are missing
               option_tags = object.tags(:option)
               return unless option_tags.empty?
@@ -40,6 +45,31 @@ module Yard
               collector.puts "#{object.file}:#{object.line}: #{object.title}"
               collector.puts params.map { |p| p.join(' ') }.join(', ')
             end
+
+            private
+
+            # Whether a named options-style parameter is documented with a
+            # concrete non-Hash @param type (e.g. `@param option [Symbol]`).
+            # Double-splat (`**opts`) collectors are always hashes and excluded.
+            # @param object [YARD::CodeObjects::MethodObject] the method
+            # @return [Boolean]
+            def options_param_documented_as_non_hash?(object)
+              param_tags = all_typed_tags(object.docstring, %w[param])
+
+              object.parameters.any? do |param|
+                name = param[0].to_s
+                next false if name.start_with?('**')
+
+                bare = name.gsub(/[*:]/, '')
+                next false unless bare.match?(/\A(options?|opts?|kwargs)\z/)
+
+                tag = param_tags.find { |t| t.name == bare }
+                types = tag&.types
+                next false if types.nil? || types.empty?
+
+                types.none? { |type| type.to_s.match?(/\AHash\b|\AHash[<{(]/) }
+              end
+            end
           end
         end
       end

data/lib/yard/lint/validators/semantic/abstract_methods/result.rb

@@ -28,6 +28,7 @@ module Yard
                   severity: configured_severity,
                   type: self.class.offense_type,
                   name: offense_data[:name] || self.class.offense_name,
+                  validator: validator_name,
                   message: build_message(offense_data),
                   location: offense_data[:location] || offense_data[:file],
                   location_line: offense_data[:line] || offense_data[:location_line] || 0

data/lib/yard/lint/validators/semantic/abstract_methods/validator.rb

@@ -32,11 +32,21 @@ module Yard
               # Skip def line and end
               body_lines = lines[1...-1] || []
 
+              # Merge statement continuations (a line ending in a comma or
+              # backslash continues on the next line) so a multi-line
+              # `raise NotImplementedError, "message"` is judged as one
+              # statement rather than leaving a dangling argument line that
+              # looks like a real implementation.
+              body_lines = merge_continuations(body_lines)
+
+              # A line is an allowed (non-)implementation if it is a comment,
+              # the closing `end`, or matches one of the configured
+              # AllowedImplementations patterns (e.g. raising NotImplementedError).
+              allowed = allowed_implementation_patterns
               has_real_implementation = body_lines.any? do |line|
-                !line.start_with?('#') &&
-                  !line.include?('NotImplementedError') &&
-                  !line.include?('raise') &&
-                  line != 'end'
+                next false if line.start_with?('#') || line == 'end'
+
+                allowed.none? { |pattern| line.match?(pattern) }
               end
 
               return unless has_real_implementation
@@ -44,6 +54,35 @@ module Yard
               collector.puts "#{object.file}:#{object.line}: #{object.title}"
               collector.puts 'has_implementation'
             end
+
+            private
+
+            # The configured AllowedImplementations patterns compiled to
+            # regexps. A body line matching any of these does not count as a
+            # real implementation. Invalid patterns are ignored.
+            # @return [Array<Regexp>]
+            def allowed_implementation_patterns
+              Array(config_or_default('AllowedImplementations')).filter_map do |pattern|
+                Regexp.new(pattern.to_s)
+              rescue RegexpError
+                nil
+              end
+            end
+
+            # Joins lines that are continuations of the previous statement (the
+            # previous line ends with a comma or a backslash) into a single
+            # logical line.
+            # @param lines [Array<String>] stripped body lines
+            # @return [Array<String>] body lines with continuations merged
+            def merge_continuations(lines)
+              lines.each_with_object([]) do |line, merged|
+                if !merged.empty? && merged.last.match?(/[,\\]\z/)
+                  merged[-1] = "#{merged.last.chomp('\\').rstrip} #{line}"
+                else
+                  merged << line
+                end
+              end
+            end
           end
         end
       end

data/lib/yard/lint/validators/tags/api_tags/validator.rb

@@ -19,7 +19,12 @@ module Yard
               allowed_list = allowed_apis
 
               if object.has_tag?(:api)
-                api_value = object.tag(:api).text
+                # YARD tag text includes indented continuation/description lines
+                # (e.g. "private\nfor internal use only"). The @api value is a
+                # single token, so validate only the first word - otherwise a
+                # documented `@api private` is flagged as invalid, and the
+                # newline in the emitted value corrupts the parser's pairing.
+                api_value = object.tag(:api).text.to_s.split(/\s+/).first.to_s
                 unless allowed_list.include?(api_value)
                   collector.puts "#{object.file}:#{object.line}: #{object.title}"
                   collector.puts "invalid:#{api_value}"
@@ -37,6 +42,11 @@ module Yard
                 # hit the branch above and get their value validated. See issue #128.
                 return if object.type == :method && object.is_attribute?
 
+                # An api tag is expected on classes, modules, and methods (per
+                # this validator's documentation) - not on constants or other
+                # object types, which were being flagged as missing the tag.
+                return unless %i[class module method].include?(object.type)
+
                 # Only check public methods/classes if require_api_tags is enabled
                 visibility = object.visibility.to_s
                 if visibility == 'public' && !object.root?

data/lib/yard/lint/validators/tags/collection_type/messages_builder.rb

@@ -54,13 +54,44 @@ module Yard
                   # (String, Integer) -> Array(String, Integer)
                   "Array#{type_string}"
                 else
-                  # Hash<K, V> -> Hash{K => V}
-                  type_string.gsub(/Hash<(.+?)>/) do
-                    types = ::Regexp.last_match(1)
-                    # Split on comma, handle nested types
-                    "Hash{#{types.sub(/,\s*/, ' => ')}}"
+                  # Hash<K, V> -> Hash{K => V}, handling nested generics with
+                  # balanced-bracket splitting so the suggestion stays valid.
+                  convert_hash_short_to_long(type_string)
+                end
+              end
+
+              # Converts Hash<K, V> to Hash{K => V}, recursing into the key and
+              # value and splitting on the top-level comma so nested types like
+              # Hash<Symbol, Hash<String, Integer>> are not mangled.
+              # @param type_string [String] the type string
+              # @return [String] the converted type string
+              def convert_hash_short_to_long(type_string)
+                match = type_string.match(/\AHash<(.+)>\z/m)
+                return type_string unless match
+
+                key, value = split_top_level(match[1])
+                return type_string unless value
+
+                "Hash{#{convert_hash_short_to_long(key.strip)} => " \
+                  "#{convert_hash_short_to_long(value.strip)}}"
+              end
+
+              # Splits a generic body on its first top-level comma, respecting
+              # nested <>, {}, and () so nested generics are kept intact.
+              # @param str [String] the inside of a generic (without the brackets)
+              # @return [Array] [key, value], or [str, nil] when there is no
+              #   top-level comma
+              def split_top_level(str)
+                depth = 0
+                str.each_char.with_index do |char, index|
+                  case char
+                  when '<', '{', '(' then depth += 1
+                  when '>', '}', ')' then depth -= 1
+                  when ','
+                    return [str[0...index], str[(index + 1)..]] if depth.zero?
                   end
                 end
+                [str, nil]
               end
 
               # Converts long syntax to short syntax