yard-lint 1.6.0 → 1.6.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: ef1425a1be17cac04595b6558a742eb4036fc1cc66891e1d8f31eb46094c8914
-  data.tar.gz: d5ba0ef812eb0261718d7259d2da0b0f0b2fa37a1674893f6d7d3178be3bf551
+  metadata.gz: 0e80922a8d6a086601b78ff5aa7d15a1463a9b772b44c3315d440d35ab8e8e36
+  data.tar.gz: ece101a1e691a92a8c524a6e1a7b63e6db623cb7c156680f0b85ca3129861821
 SHA512:
-  metadata.gz: 23d60c91521b5afbadd0a43380682686f7b10aa68a968f5091da2de425f477f71ce3b8a6477ca5d0197d7138979dffc4a0aebe2582b3a64cd4092b18b6222c95
-  data.tar.gz: 966fe65d5e72ba1dbf225fe8802f2259dcdb436a66b2571d6caf7aff7d59491e1b337c7fe4db0e68354bceebb192c89d40ed6c1229b5e2bd2f75d2f5cbde456a
+  metadata.gz: cb60b66bee32b4f7abb20d0617e576044c98e2095967d08a4776553c3435f636dcd5ca3788e5ac2b5e3de2de501d9aade4b49e11d3b5173bd5c260a706e95808
+  data.tar.gz: 01b284d20fc97cb09c362410e491544732264568e971f40194c498824210e6724bed6c72003ce1569fdc90bedfce93bb3e19e8520877158fd8b41f0eb058c2d2

data/CHANGELOG.md

@@ -1,5 +1,8 @@
 # YARD-Lint Changelog
 
+## 1.6.1 (2026-06-11)
+- **[Fix]** `Documentation/OrphanedDocComment` no longer reports false positives for documented DSL-style method calls (e.g. `ransacker :foo do … end`, `validates :name`, `scope :active, -> { … }`). YARD's DSL handler turns such a call into a documentable method object when the preceding comment carries an implicit-docstring tag (`@return`, `@overload`, `@method`, `@attribute`, `@scope`, `@visibility`), so the comment is attached rather than dropped. The validator now recognises this case: a tagged comment before a DSL call is only flagged when the call is one YARD's handler ignores (`include`, `extend`, `private :sym`, etc.) or the comment lacks an implicit-docstring tag (in which case YARD really does drop it). Also fixes a pre-existing false positive for the bare `attr :name` attribute form.
+
 ## 1.6.0 (2026-06-11)
 - **[Feature]** New `--format quickfix` output mode emits one offense per line in the standard `file:line: S: Validator: message` format. Vim users can set `makeprg=yard-lint\ --format\ quickfix\ --no-progress\ %` and navigate offenses with `:cnext`/`:cprev`; Emacs users can use it as their `compile-command` and navigate with `M-g n`/`M-g p`. Produces no output (and exits 0) when there are no offenses.
 - **[Feature]** New opt-in validator `Documentation/LineLength` detects documentation comment lines that exceed a configurable maximum length (#176). Disabled by default (`Enabled: false`) to avoid breaking existing projects; enable with `Documentation/LineLength: Enabled: true` and tune with `MaxLength: 120` (default). Uses YARD's already-parsed docstring to determine which source lines belong to the comment block, avoiding fragile backwards-scanning. Each over-length line produces a separate offense at its exact file location.

data/README.md

@@ -325,6 +325,14 @@ def greet(name); end
 # Good - constant assignments are documentable, not flagged
 # @return [Integer] the answer
 ANSWER = 42
+
+# Good - DSL calls (ransacker, validates, scope, ...) are turned into method
+# objects by YARD's DSL handler when the comment carries a tag like @return,
+# so they are documentable and not flagged
+# @return [Arel::Nodes::Node]
+ransacker :owner_name do
+  Arel.sql("...")
+end
 ```
 
 This validator is complementary to `Documentation/BlankLineBeforeDefinition` (which handles the case where blank lines separate a doc comment from a `def` - YARD still attaches it despite the gap).

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

@@ -24,13 +24,37 @@ module Yard
             # and constant assignments (uppercase-leading identifier followed by =), both of which
             # YARD tracks and attaches preceding doc comments to.
             # Also matches define_method which YARD handles via a built-in dynamic handler.
+            # `attr\b` is matched after the `attr_*` variants so the bare `attr :name` form
+            # (handled by YARD's attribute handler) is recognised without swallowing them.
             DEFINITION_PATTERN = /
               \A\s*(private\s+|protected\s+|public\s+)?
-              (def |class |module |attr_reader|attr_writer|attr_accessor|attr_internal|alias_method\b|alias\b|define_method\b)
+              (def |class |module |attr_reader|attr_writer|attr_accessor|attr_internal|attr\b|alias_method\b|alias\b|define_method\b)
               |
               \A\s*[A-Z][A-Za-z0-9_:]*\s*=
             /x.freeze
 
+            # Matches a DSL-style method call whose first argument is a symbol or string literal
+            # (e.g. `ransacker :foo do`, `validates(:name, ...)`, `scope :active, -> { ... }`).
+            # YARD's DSL handler turns such a call into a documentable method object when the
+            # preceding comment carries an implicit-docstring tag, so a doc comment in front of
+            # one of these is NOT orphaned.
+            DSL_CALL_PATTERN = /\A\s*(?<method>[a-z_]\w*[!?]?)(?:\s+|\s*\(\s*)(?::\w|:["']|["'])/.freeze
+            # Mirror of YARD::Handlers::Ruby::DSLHandlerMethods::IGNORE_METHODS - calls to these
+            # are skipped by YARD's DSL handler, so a preceding doc comment really is dropped.
+            # (The `attr*`/`alias*` entries are already covered by DEFINITION_PATTERN.)
+            DSL_IGNORE_METHODS = %w[
+              alias alias_method autoload attr attr_accessor attr_reader attr_writer
+              extend include module_function public private protected private_constant
+              private_class_method public_class_method
+            ].freeze
+            # YARD's DSL handler only creates a method object when the comment carries one of these
+            # tags (see DSLHandlerMethods#implicit_docstring?). Matched on raw comment lines because
+            # some (`@method`, `@attribute`, `@scope`, `@visibility`) are not in YARD's tag registry
+            # and would otherwise be missed by YARD_TAG_PATTERN. Directive (`@!`) forms are excluded
+            # here because directive blocks are already skipped upstream.
+            IMPLICIT_DOCSTRING_TAG_PATTERN =
+              /\A\s*#\s*@(?:method|attribute|overload|visibility|scope|return)\b/.freeze
+
             # @param object [YARD::CodeObjects::Base] the code object to query
             # @param collector [Executor::ResultCollector] collector for output
             # @return [void]
@@ -59,8 +83,10 @@ module Yard
                   tags = []
 
                   has_directive = false
+                  has_implicit_tag = false
                   while i < lines.length && comment_line?(lines[i])
                     has_directive = true if directive_line?(lines[i])
+                    has_implicit_tag = true if implicit_docstring_tag?(lines[i])
                     tag = extract_yard_tag(lines[i])
                     tags << tag if tag
                     i += 1
@@ -73,7 +99,7 @@ module Yard
                   # Skip trailing blank lines after the comment block
                   i += 1 while i < lines.length && lines[i].strip.empty?
 
-                  if i >= lines.length || !definition_line?(lines[i])
+                  unless documentable?(lines[i], has_implicit_tag)
                     collector.puts "#{file}:#{block_start + 1}: #{tags.uniq.join(',')}"
                   end
                 else
@@ -108,11 +134,37 @@ module Yard
               "@#{match[1]}" if match
             end
 
+            # @param line [String, nil] the source line following the comment block, or nil at EOF
+            # @param has_implicit_tag [Boolean] whether the comment block carries a tag that makes
+            #   YARD's DSL handler emit a method object (see IMPLICIT_DOCSTRING_TAG_PATTERN)
+            # @return [Boolean] true if YARD will attach the comment to a documentable construct
+            def documentable?(line, has_implicit_tag)
+              return false if line.nil?
+
+              definition_line?(line) || (has_implicit_tag && dsl_method_line?(line))
+            end
+
             # @param line [String] a raw source line
             # @return [Boolean] true if the line starts a YARD-documentable definition
             def definition_line?(line)
               line.match?(DEFINITION_PATTERN)
             end
+
+            # @param line [String] a raw source line
+            # @return [Boolean] true if the line is a DSL-style call YARD's handler documents
+            #   (symbol/string first argument and not one of YARD's ignored methods)
+            def dsl_method_line?(line)
+              match = line.match(DSL_CALL_PATTERN)
+              return false unless match
+
+              !DSL_IGNORE_METHODS.include?(match[:method])
+            end
+
+            # @param line [String] a raw source line
+            # @return [Boolean] true if the comment line carries an implicit-docstring tag
+            def implicit_docstring_tag?(line)
+              line.match?(IMPLICIT_DOCSTRING_TAG_PATTERN)
+            end
           end
         end
       end

data/lib/yard/lint/version.rb

@@ -3,6 +3,6 @@
 module Yard
   module Lint
     # @return [String] version of the YARD Lint gem
-    VERSION = '1.6.0'
+    VERSION = '1.6.1'
   end
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: yard-lint
 version: !ruby/object:Gem::Version
-  version: 1.6.0
+  version: 1.6.1
 platform: ruby
 authors:
 - Maciej Mensfeld