yard-lint 1.10.0 → 1.10.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 37286ca0e1a4253fd44af81beda164e713f58903e9d7c06ccf7dc06484c76be9
-  data.tar.gz: 2b5b3dc5eaed758b12b07a5a2a67ad537dbf56e8459a5075e796850a73deb2a2
+  metadata.gz: 0c63ea819ad85e3c0878e26d37ea3b59bb61598804d3963425ff5882931b1a22
+  data.tar.gz: 5b613e3ba58f6773abd4b47b23c64e94d223ddecde10a743db5de1525b0f5ec2
 SHA512:
-  metadata.gz: ca788e4ee2a91c5990b20c953bf28bfeaa731c6feaa4183a3bb323e04f5a198af40a7f30d60e4a714d9361a0ab589a9c202f766202e7c6468ad7c7407b55d5ea
-  data.tar.gz: a38ddad77479fdcc11f18d530fafacd090d079827a1e93ad423f2dc839e5e50cc072ab04a7a2150836f4f654f560e098abf6e59c5b38d970f6d93d39a373b8cf
+  metadata.gz: 608923c037bde8d53573ae6f7d3487d1b156ba04ae94c143675c5c5f6c541ccb6266df7acf1748e7fd54e9e3bb92942a28fd2d62d560b92b6ee6e5373f60c822
+  data.tar.gz: 91863e353c9be138fa4bd93db36ce4cdf85209a85863dca25f6d7c1f3a794673018946d7e8160fedf801a4c80cf7377359f675462d87c7955aaf4b80fcffa68f

data/CHANGELOG.md

@@ -1,3 +1,6 @@
+## 1.10.1 (2026-07-24)
+- **[Bugfix]** `Documentation/BlankLineBeforeDefinition` no longer reports a foreign comment block above a definition as documentation that was accidentally detached from it. When the object is documented (non-empty docstring) but that docstring did not come from the comment block sitting above this definition, the block is not a detached docstring - it is a file-level license/copyright banner, an encoding note, or an unrelated comment above a namespace reopening whose documentation lives in another file. The check compares the object's docstring against the block's text, so it recognizes any such banner without hardcoding its wording. Definitions whose documentation was genuinely lost (an undocumented object with a comment block detached above it) are still reported.
+
 ## 1.10.0 (2026-07-24)
 - **[Feature]** Added `Documentation/DuplicateNamespaceComment` (enabled by default, severity `warning`) - detects namespaces (modules and classes) that carry a YARD documentation comment in more than one file. When a namespace is reopened across files and documented in several of them, YARD merges the reopenings into a single object and keeps only one docstring, silently discarding the rest (the last documented reopening wins, with no warning), so competing descriptions are lost. This is a common accident for shared namespaces (e.g. `Users` or `Users::Operations`) spread across many files; it does not affect a leaf object such as `Users::Operations::Create` that lives in a single file. Because YARD does not record which reopening carried a comment, the validator re-reads each definition site to detect the documented ones (ignoring blank-line-detached comments and directive/magic comments), and reports one offense per namespace documented in two or more files, listing every documented location and noting when the docstrings differ (meaning content is actually lost). Configurable via the standard `Enabled` and `Severity` keys.
 

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

@@ -21,9 +21,19 @@ module Yard
               source_lines = File.readlines(object.file)
               definition_line = object.line - 1
 
-              blank_count, has_doc_block = analyze_spacing(source_lines, definition_line)
+              blank_count, doc_block_line = analyze_spacing(source_lines, definition_line)
 
-              return if blank_count.zero? || !has_doc_block
+              return if blank_count.zero? || doc_block_line.nil?
+
+              # Only a comment block that is genuinely THIS object's documentation can have
+              # been detached from it by the blank line. When the object is documented (its
+              # docstring is non-empty) but that docstring did not come from the comment block
+              # sitting above this definition, the block is a foreign comment - a file-level
+              # license/copyright banner, an encoding note, or an unrelated comment above a
+              # namespace reopening that is documented in another file - and the blank line is
+              # intentional. This is decided by comparing the object's docstring against the
+              # block's text, so it covers any such banner without hardcoding its wording.
+              return if foreign_comment_block?(object, source_lines, doc_block_line)
 
               violation_type = blank_count >= 2 ? 'orphaned' : 'single'
 
@@ -38,10 +48,10 @@ module Yard
             # Analyze spacing between documentation and definition
             # @param source_lines [Array<String>] lines of source file
             # @param definition_line [Integer] 0-indexed line of definition
-            # @return [Array<Integer, Boolean>] blank count and whether doc block exists
+            # @return [Array<Integer, Integer, nil>] blank count and the 0-indexed line of the
+            #   nearest documentation comment above the definition (nil when there is none)
             def analyze_spacing(source_lines, definition_line)
               blank_count = 0
-              has_doc_block = false
 
               (definition_line - 1).downto(0) do |i|
                 line = source_lines[i].to_s.rstrip
@@ -56,15 +66,65 @@ module Yard
                   # spurious blank-line offenses for undocumented definitions.
                   next if non_documentation_comment?(stripped)
 
-                  has_doc_block = true
-                  break
+                  return [blank_count, i]
                 else
                   # Non-comment, non-blank line - no documentation above
                   break
                 end
               end
 
-              [blank_count, has_doc_block]
+              [blank_count, nil]
+            end
+
+            # Whether the comment block above the definition is NOT the source of the object's
+            # documentation - a file banner or an unrelated comment rather than a docstring
+            # this definition lost to the blank line.
+            #
+            # An object with no docstring at all has genuinely orphaned documentation, so the
+            # block above is still reported. When the object IS documented, the block only
+            # counts as detached documentation if the docstring's text actually came from it;
+            # a license header or a comment above a reopening documented elsewhere carries
+            # different text and is left alone.
+            # @param object [YARD::CodeObjects::Base] the code object being checked
+            # @param source_lines [Array<String>] lines of source file
+            # @param doc_line [Integer] 0-indexed line of the nearest comment above the definition
+            # @return [Boolean]
+            def foreign_comment_block?(object, source_lines, doc_line)
+              docstring = object.docstring.to_s.strip
+              return false if docstring.empty?
+
+              block = comment_block_text(source_lines, doc_line)
+              first_line = normalize(docstring.lines.first.to_s)
+              return false if first_line.empty?
+
+              !normalize(block).include?(first_line)
+            end
+
+            # Text of the contiguous comment block that contains `doc_line`, stripped of the
+            # comment markers and joined into a single string.
+            # @param source_lines [Array<String>] lines of source file
+            # @param doc_line [Integer] 0-indexed line within the comment block
+            # @return [String]
+            def comment_block_text(source_lines, doc_line)
+              first = doc_line
+              first -= 1 while first.positive? && comment_line?(source_lines[first - 1])
+              last = doc_line
+              last += 1 while last + 1 < source_lines.length && comment_line?(source_lines[last + 1])
+
+              source_lines[first..last].map { |line| line.sub(/\A\s*#+\s?/, '').strip }.join(' ')
+            end
+
+            # @param line [String, nil] a source line
+            # @return [Boolean] whether the line is a comment line
+            def comment_line?(line)
+              line.to_s.strip.start_with?('#')
+            end
+
+            # Collapse whitespace so wrapped docstrings and their source comments compare equal.
+            # @param text [String]
+            # @return [String]
+            def normalize(text)
+              text.strip.gsub(/\s+/, ' ')
             end
 
             # Check if a comment line is a Ruby magic comment

data/lib/yard/lint/version.rb

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

metadata

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