Support hover information for parameter variable

definitions.

This is mainly usefull when you are working in a project with large
docblocks that define some types that are hard to discover, so making
the hover work for them allow you to easier discover the actual type of
the variable.

Author: RemcoSmitsDev

docs/CHANGELOG.md

@@ -44,6 +44,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - **Add iterable return type code action.** When PHPStan reports `missingType.iterableValue` for a return type (e.g. "return type has no value type specified in iterable type array"), a quickfix adds a `@return` docblock tag with the element type inferred from the function body. For example, a function returning `$array = ['hello']` produces `@return array<string>` rather than `array<mixed>`. Falls back to `<mixed>` only when the element type cannot be determined. Existing docblocks are updated in place; single-line docblocks are expanded to multi-line. The diagnostic is eagerly cleared once the `@return` tag contains a generic type.
 - **Remove unreachable statement code action.** When PHPStan reports `deadCode.unreachable`, a quickfix deletes the dead statement. The statement-removal helper is shared infrastructure that a future native dead-code diagnostic (D6) can reuse.
 - **Eloquent `$appends` array.** Entries in a model's `$appends` property now produce virtual properties, matching the existing treatment of `$fillable`, `$guarded`, `$hidden`, and `$visible`.
+- **Hover on parameter variables at their definition site.** Hovering on a function or method parameter now shows its resolved type instead of being suppressed. When a `@param` tag provides a richer type than the native hint (e.g. `list<Pen>` vs `array`), the docblock type is shown. Contributed by @RemcoSmitsDev in https://github.com/AJenbo/phpantom_lsp/pull/68.
 
 ### Changed
 

src/completion/resolver.rs

@@ -524,8 +524,8 @@ pub(crate) fn resolve_target_classes(
     // vec would poison the cache: a later top-level lookup (at
     // depth 0) would hit the cached empty entry and produce a
     // false "type could not be resolved" diagnostic.
-    let skip_cache = result.is_empty()
-        && super::variable::resolution::is_var_resolution_depth_limited();
+    let skip_cache =
+        result.is_empty() && super::variable::resolution::is_var_resolution_depth_limited();
     if !skip_cache {
         DIAG_SUBJECT_CACHE.with(|cell| {
             let mut borrow = cell.borrow_mut();

src/completion/variable/rhs_resolution.rs

@@ -479,15 +479,20 @@ fn resolve_rhs_instantiation(
                         // is not yet known.  Now that generic args are concrete,
                         // resolve those mixins and merge their members.
                         if cls.mixins.iter().any(|m| cls.template_params.contains(m)) {
-                            let generic_subs = crate::inheritance::build_generic_subs(cls, &type_args);
+                            let generic_subs =
+                                crate::inheritance::build_generic_subs(cls, &type_args);
                             if !generic_subs.is_empty() {
-                                let mixin_members = crate::virtual_members::phpdoc::resolve_template_param_mixins(
-                                    cls,
-                                    &generic_subs,
-                                    ctx.class_loader,
-                                );
+                                let mixin_members =
+                                    crate::virtual_members::phpdoc::resolve_template_param_mixins(
+                                        cls,
+                                        &generic_subs,
+                                        ctx.class_loader,
+                                    );
                                 if !mixin_members.is_empty() {
-                                    crate::virtual_members::merge_virtual_members(&mut substituted, mixin_members);
+                                    crate::virtual_members::merge_virtual_members(
+                                        &mut substituted,
+                                        mixin_members,
+                                    );
                                 }
                             }
                         }

src/hover/mod.rs

@@ -502,14 +502,15 @@ impl Backend {
             SymbolKind::Variable { name } => {
                 // Suppress hover when the cursor is on a variable at its
                 // definition site where the type is already visible in
-                // the signature (parameters, properties, static/global
-                // declarations).  For assignments, foreach bindings, and
-                // catch bindings the resolved type is not obvious from the
-                // source text, so hover is useful there.
+                // the signature (properties, static/global declarations).
+                // For parameters, assignments, foreach bindings, and catch
+                // bindings, hover is useful to show the resolved type and
+                // any docblock descriptions.
                 if let Some(def_kind) = self.lookup_var_def_kind_at(uri, name, cursor_offset)
                     && !matches!(
                         def_kind,
                         VarDefKind::Assignment
+                            | VarDefKind::Parameter
                             | VarDefKind::Foreach
                             | VarDefKind::Catch
                             | VarDefKind::ArrayDestructuring

src/inheritance.rs

@@ -1007,7 +1007,10 @@ pub(crate) fn apply_substitution<'a>(
 ///
 /// Returns an empty map when no substitutions can be made (e.g. when
 /// `template_params` or `type_args` is empty).
-pub(crate) fn build_generic_subs(class: &ClassInfo, type_args: &[&str]) -> HashMap<String, PhpType> {
+pub(crate) fn build_generic_subs(
+    class: &ClassInfo,
+    type_args: &[&str],
+) -> HashMap<String, PhpType> {
     if class.template_params.is_empty() || type_args.is_empty() {
         return HashMap::new();
     }

tests/integration/hover.rs

@@ -398,29 +398,94 @@ class Consumer {
 }
 
 #[test]
-fn hover_suppressed_on_parameter_definition_site() {
+fn hover_active_on_parameter_definition_site() {
     let backend = create_test_backend();
     let uri = "file:///test.php";
     let content = r#"<?php
-class Builder {
-    public function scopeOfGenre(\Illuminate\Database\Eloquent\Builder $query, string $genre): void {
-        $query->where('genre', $genre);
+class Order { public string $id; }
+class Service {
+    public function process(Order $query, string $genre): void {
+        $query;
     }
 }
 "#;
 
-    // Hover on `$query` at the parameter definition site (line 2, col ~72)
-    let hover = hover_at(&backend, uri, content, 2, 73);
+    // Hover on `$query` at the parameter definition site (line 3, col on $query)
+    let hover = hover_at(&backend, uri, content, 3, 35)
+        .expect("hover should be active on parameter $query");
+    let text = hover_text(&hover);
     assert!(
-        hover.is_none(),
-        "hover should be suppressed on parameter $query"
+        text.contains("$query"),
+        "hover should show the parameter name: {}",
+        text
+    );
+    assert!(
+        text.contains("Order"),
+        "hover should show the resolved type Order: {}",
+        text
     );
 
-    // Hover on `$genre` at the parameter definition site (line 2, col ~87)
-    let hover = hover_at(&backend, uri, content, 2, 88);
+    // Hover on `$genre` at the parameter definition site (line 3, col on $genre)
+    let hover = hover_at(&backend, uri, content, 3, 50)
+        .expect("hover should be active on parameter $genre");
+    let text = hover_text(&hover);
     assert!(
-        hover.is_none(),
-        "hover should be suppressed on parameter $genre"
+        text.contains("$genre") && text.contains("string"),
+        "hover should show the parameter name and type: {}",
+        text
+    );
+}
+
+#[test]
+fn hover_parameter_definition_shows_docblock_type() {
+    let backend = create_test_backend();
+    let uri = "file:///test.php";
+    let content = r#"<?php
+class Pen { public function write(): string { return ''; } }
+class Drawer {
+    /** @param list<Pen> $pens The pens to use. */
+    public function fill(array $pens): void {
+        $pens;
+    }
+}
+"#;
+
+    // Hover on `$pens` at the parameter definition site (line 4)
+    let hover = hover_at(&backend, uri, content, 4, 33)
+        .expect("hover should be active on parameter $pens with docblock type");
+    let text = hover_text(&hover);
+    assert!(
+        text.contains("$pens"),
+        "hover should show the parameter name: {}",
+        text
+    );
+}
+
+#[test]
+fn hover_parameter_definition_standalone_function() {
+    let backend = create_test_backend();
+    let uri = "file:///test.php";
+    let content = r#"<?php
+class Pen { public function write(): string { return ''; } }
+/** @param Pen $tool The writing instrument. */
+function draw(Pen $tool): void {
+    $tool;
+}
+"#;
+
+    // Hover on `$tool` at the parameter definition site (line 3)
+    let hover = hover_at(&backend, uri, content, 3, 19)
+        .expect("hover should be active on standalone function parameter $tool");
+    let text = hover_text(&hover);
+    assert!(
+        text.contains("$tool"),
+        "hover should show the parameter name: {}",
+        text
+    );
+    assert!(
+        text.contains("Pen"),
+        "hover should show the type Pen: {}",
+        text
     );
 }