Docblock Override

Author: AJenbo

docs/todo.md

@@ -30,29 +30,6 @@ target.
 
 ### Remaining by user need
 
-#### 39. `@var` type annotation without variable name not resolved
-
-When a `@var` docblock includes the variable name, the type is picked up
-correctly. When the variable name is omitted (a common shorthand), the
-type is not applied to the next assignment.
-
-```php
-// Works:
-/** @var User $red */
-$red = a();
-$red->  // ← completes User members
-
-// Does not work:
-/** @var User */
-$red = a();
-$red->  // ← no completion
-```
-
-**Fix:** when `@var` has a type but no variable name, apply the type to
-the immediately following assignment statement.
-
----
-
 #### 40. No nested key completion for literal array assignments
 
 When a variable is assigned a literal array with nested associative

example.php

@@ -59,13 +59,25 @@
 $user->render();             // @method (Renderable interface)
 
 
+// ── @var Docblock Override ──────────────────────────────────────────────────
+// The variable name in @var is optional. Both forms work for completion and go-to-definition.
+
+/** @var AdminUser $inlineHinted */
+$inlineHinted = getUnknownValue();
+$inlineHinted->grantPermission('write');  // with explicit variable name
+
+/** @var User */
+$hinted = getUnknownValue();
+$hinted->getEmail();                      // type from @var, no variable name needed
+
+
 // ── String Interpolation ────────────────────────────────────────────────────
 // Completion is suppressed inside plain string content but still works in
 // PHP interpolation contexts. Try: delete the property name after -> and
 // trigger completion to see members offered.
 
-$greeting = "Hello {$user->getProfile()->bio}";   // brace interpolation — completion works
-$info = "Name: $user->displayName";               // simple interpolation — completion works
+$greeting = "Hello {$user->getProfile()->bio}";   // brace interpolation — full completion
+$info = "Name: $user->displayName";               // simple interpolation — completion only for valid items
 $nope = 'no $user-> here';                        // single-quoted — completion suppressed
 $plain = "just plain text";                       // no $ — completion suppressed
 
@@ -208,17 +220,6 @@ function handleIntersection(User&Loggable $entity): void {
 $p->getDisplayName();                     // Profile → UserProfile via `use ... as`
 
 
-// ── @var Docblock Override ──────────────────────────────────────────────────
-
-/** @var User $hinted */
-$hinted = getUnknownValue();
-$hinted->getEmail();                      // type from @var, not mixed
-
-/** @var AdminUser $inlineHinted */
-$inlineHinted = getUnknownValue();
-$inlineHinted->grantPermission('write');
-
-
 // ── Ambiguous Variables ─────────────────────────────────────────────────────
 
 if (rand(0, 1)) {

tests/completion_variables.rs

@@ -2494,6 +2494,151 @@ async fn test_completion_inline_var_docblock_override_allowed_for_object() {
     }
 }
 
+/// Inline `@var` without variable name at top level resolves the type
+/// for the immediately following assignment.
+#[tokio::test]
+async fn test_completion_inline_var_docblock_no_varname_top_level() {
+    let backend = create_test_backend();
+
+    let uri = Url::parse("file:///inlinevar_toplevel.php").unwrap();
+    let text = concat!(
+        "<?php\n",
+        "class User {\n",
+        "    public string $name;\n",
+        "    public function getEmail(): string {}\n",
+        "}\n",
+        "/** @var User */\n",
+        "$red = a();\n",
+        "$red->\n",
+    );
+
+    let open_params = DidOpenTextDocumentParams {
+        text_document: TextDocumentItem {
+            uri: uri.clone(),
+            language_id: "php".to_string(),
+            version: 1,
+            text: text.to_string(),
+        },
+    };
+    backend.did_open(open_params).await;
+
+    let completion_params = CompletionParams {
+        text_document_position: TextDocumentPositionParams {
+            text_document: TextDocumentIdentifier { uri },
+            position: Position {
+                line: 7,
+                character: 6,
+            },
+        },
+        work_done_progress_params: WorkDoneProgressParams::default(),
+        partial_result_params: PartialResultParams::default(),
+        context: None,
+    };
+
+    let result = backend.completion(completion_params).await.unwrap();
+    assert!(
+        result.is_some(),
+        "Should return completions for @var User without variable name at top level"
+    );
+
+    match result.unwrap() {
+        CompletionResponse::Array(items) => {
+            let names: Vec<&str> = items
+                .iter()
+                .map(|i| i.filter_text.as_deref().unwrap_or(&i.label))
+                .collect();
+            assert!(
+                names.contains(&"name"),
+                "Should include 'name' from User, got: {:?}",
+                names
+            );
+            assert!(
+                names.contains(&"getEmail"),
+                "Should include 'getEmail' from User, got: {:?}",
+                names
+            );
+        }
+        _ => panic!("Expected CompletionResponse::Array"),
+    }
+}
+
+/// Inline `@var` without variable name for a cross-file class at top level.
+#[tokio::test]
+async fn test_completion_inline_var_docblock_no_varname_cross_file() {
+    let (backend, _dir) = create_psr4_workspace(
+        r#"{ "autoload": { "psr-4": { "App\\": "src/" } } }"#,
+        &[(
+            "src/Models/User.php",
+            concat!(
+                "<?php\n",
+                "namespace App\\Models;\n",
+                "class User {\n",
+                "    public string $name;\n",
+                "    public function getEmail(): string {}\n",
+                "}\n",
+            ),
+        )],
+    );
+
+    let uri = Url::parse("file:///crossfile_inlinevar.php").unwrap();
+    let text = concat!(
+        "<?php\n",
+        "use App\\Models\\User;\n",
+        "/** @var User */\n",
+        "$red = a();\n",
+        "$red->\n",
+    );
+
+    let open_params = DidOpenTextDocumentParams {
+        text_document: TextDocumentItem {
+            uri: uri.clone(),
+            language_id: "php".to_string(),
+            version: 1,
+            text: text.to_string(),
+        },
+    };
+    backend.did_open(open_params).await;
+
+    let completion_params = CompletionParams {
+        text_document_position: TextDocumentPositionParams {
+            text_document: TextDocumentIdentifier { uri },
+            position: Position {
+                line: 4,
+                character: 6,
+            },
+        },
+        work_done_progress_params: WorkDoneProgressParams::default(),
+        partial_result_params: PartialResultParams::default(),
+        context: None,
+    };
+
+    let result = backend.completion(completion_params).await.unwrap();
+    assert!(
+        result.is_some(),
+        "Should return completions for cross-file @var User without variable name"
+    );
+
+    match result.unwrap() {
+        CompletionResponse::Array(items) => {
+            let names: Vec<&str> = items
+                .iter()
+                .map(|i| i.filter_text.as_deref().unwrap_or(&i.label))
+                .collect();
+            assert!(
+                names.contains(&"name"),
+                "Should include 'name' from User, got: {:?}",
+                names
+            );
+            assert!(
+                names.contains(&"getEmail"),
+                "Should include 'getEmail' from User, got: {:?}",
+                names
+            );
+        }
+        _ => panic!("Expected CompletionResponse::Array"),
+    }
+}
+
 #[tokio::test]
 async fn test_completion_inline_var_docblock_unconditional_reassignment() {
     let backend = create_test_backend();

tests/definition_variables.rs

@@ -625,6 +625,70 @@ async fn test_goto_definition_inline_var_docblock_simple() {
     }
 }
 
+/// When the `@var` annotation omits the variable name (`/** @var Type */`),
+/// goto definition should apply the type to the immediately following
+/// assignment and resolve the member correctly.
+#[tokio::test]
+async fn test_goto_definition_inline_var_docblock_no_variable_name() {
+    let backend = create_test_backend();
+
+    let uri = Url::parse("file:///varoverride_noname.php").unwrap();
+    let text = concat!(
+        "<?php\n",                                  // 0
+        "class Session {\n",                        // 1
+        "    public function getId(): string {}\n", // 2
+        "    public function flash(): void {}\n",   // 3
+        "}\n",                                      // 4
+        "class Controller {\n",                     // 5
+        "    public function handle() {\n",         // 6
+        "        /** @var Session */\n",            // 7
+        "        $sess = mystery();\n",             // 8
+        "        $sess->flash();\n",                // 9
+        "    }\n",                                  // 10
+        "}\n",                                      // 11
+    );
+
+    let open_params = DidOpenTextDocumentParams {
+        text_document: TextDocumentItem {
+            uri: uri.clone(),
+            language_id: "php".to_string(),
+            version: 1,
+            text: text.to_string(),
+        },
+    };
+    backend.did_open(open_params).await;
+
+    // Click on "flash" on line 9: $sess->flash()
+    let params = GotoDefinitionParams {
+        text_document_position_params: TextDocumentPositionParams {
+            text_document: TextDocumentIdentifier { uri: uri.clone() },
+            position: Position {
+                line: 9,
+                character: 16,
+            },
+        },
+        work_done_progress_params: WorkDoneProgressParams::default(),
+        partial_result_params: PartialResultParams::default(),
+    };
+
+    let result = backend.goto_definition(params).await.unwrap();
+    assert!(
+        result.is_some(),
+        "Should resolve $sess->flash() via @var Session annotation (no variable name)"
+    );
+
+    match result.unwrap() {
+        GotoDefinitionResponse::Scalar(location) => {
+            assert_eq!(location.uri, uri);
+            assert_eq!(
+                location.range.start.line, 3,
+                "flash() is declared on line 3 in Session"
+            );
+        }
+        other => panic!("Expected Scalar location, got: {:?}", other),
+    }
+}
+
 /// When the `@var` annotation includes a variable name (`@var Type $var`),
 /// goto definition should still resolve correctly.
 #[tokio::test]