fix(syntax): ignore trivia between docblock and statement

closes #571

Signed-off-by: azjezz <[email protected]>

Author: azjezz

crates/analyzer/tests/cases/issue_571.php

@@ -0,0 +1,62 @@
+<?php
+
+declare(strict_types=1);
+
+interface Column
+{
+    public function name(): string;
+}
+
+final class FlatColumn implements Column
+{
+    public function __construct(
+        private string $name,
+    ) {}
+
+    public function name(): string
+    {
+        return $this->name;
+    }
+}
+
+final class NestedColumn implements Column
+{
+    public function __construct(
+        private string $name,
+    ) {}
+
+    public function name(): string
+    {
+        return $this->name;
+    }
+
+    public function isList(): bool
+    {
+        return true;
+    }
+}
+
+function processNestedColumn(NestedColumn $column): void
+{
+    echo 'Processing nested column: ' . $column->name() . "\n";
+}
+
+function process(Column $column): void
+{
+    if ($column instanceof FlatColumn) {
+        echo "Flat column\n";
+        return;
+    }
+
+    /**
+     * @var NestedColumn $column
+     */
+    // Comment after docblock should not prevent docblock from being recognized
+    // 
+    // 
+    // Some comment here
+    // 
+    /* another */
+    # and this
+    processNestedColumn($column);
+}

crates/analyzer/tests/mod.rs

@@ -395,6 +395,7 @@ test_case!(issue_564);
 test_case!(issue_567);
 test_case!(issue_568);
 test_case!(issue_570);
+test_case!(issue_571);
 test_case!(issue_573);
 test_case!(issue_549);
 test_case!(issue_551);

crates/syntax/src/comments/docblock.rs

@@ -55,32 +55,34 @@ pub fn get_docblock_before_position<'arena>(
         return None;
     }
 
+    // Track the earliest position we've "covered" by trivia.
+    // Start from node_start_offset and work backwards.
+    // As we iterate, we verify that each trivia connects to the next (no code gaps).
+    let mut covered_from = node_start_offset;
+
     for i in (0..candidate_partition_idx).rev() {
         let trivia = &trivias[i];
+        let trivia_end = trivia.span.end_offset();
 
-        match trivia.kind {
-            TriviaKind::DocBlockComment => {
-                let docblock_end_offset = trivia.span().end.offset;
-
-                // Get the slice between docblock end and class start
-                let code_between_slice = file
-                    .contents
-                    .as_bytes()
-                    .get(docblock_end_offset as usize..node_start_offset as usize)
-                    .unwrap_or(&[]);
+        // Check if there's a gap between this trivia and our covered region.
+        // If there's non-whitespace content in the gap, there's actual code between them.
+        let gap_slice = file.contents.as_bytes().get(trivia_end as usize..covered_from as usize).unwrap_or(&[]);
 
-                if code_between_slice.iter().all(u8::is_ascii_whitespace) {
-                    // It's the correct docblock!
-                    return Some(trivia);
-                }
+        if !gap_slice.iter().all(u8::is_ascii_whitespace) {
+            // There's actual code in the gap. No docblock applies.
+            return None;
+        }
 
-                // There was non-whitespace code between this docblock and the class.
-                // This docblock doesn't apply. Stop searching.
-                return None;
+        match trivia.kind {
+            TriviaKind::DocBlockComment => {
+                // Found a docblock with no code between it and the node.
+                return Some(trivia);
             }
-            TriviaKind::WhiteSpace => {}
-            _ => {
-                return None;
+            TriviaKind::WhiteSpace
+            | TriviaKind::SingleLineComment
+            | TriviaKind::MultiLineComment
+            | TriviaKind::HashComment => {
+                covered_from = trivia.span.start_offset();
             }
         }
     }