Skip to content

Fix docstring fallback on hover for matched overload without docstring - #12045

Open
Vishal Raj (vishalrajofficial) wants to merge 3 commits into
microsoft:mainfrom
vishalrajofficial:fix/overload-hover-docstring
Open

Vishal Raj (vishalrajofficial) wants to merge 3 commits into
microsoft:mainfrom
vishalrajofficial:fix/overload-hover-docstring

Conversation

@vishalrajofficial

Copy link
Copy Markdown

Summary

Fixes #12042.

When hovering over an overloaded function call site, hover information should display the docstring of the matched overload or fall back to the function implementation docstring. Previously, if the matched overload had no docstring and the implementation had no docstring, _selectMemberDocInfo fell through to Tier 3, returning the docstring of the first sibling overload in declaration order. This caused calls matching an undocumented overload (such as fun(b"")) to display an unrelated overload's docstring (such as "int overload").

This change ensures Tier 3 (evaluating other overloads in declaration order) only runs when no specific overload was matched for the reference (e.g. uncalled function hover).

Evidence and validation

Added focused fourslash regression coverage in packages/pyright-internal/src/tests/fourslash/hover.overloadedFunction.docstring.fourslash.ts covering:

  • Overload calls with matching docstrings (fun(1), fun(""))
  • Overload call where matched overload has no docstring (fun(b"")), verifying it does not display the first overload's docstring
  • Uncalled function reference (fun), verifying it falls back to the declared overload docstring

Ran fourslash tests locally:
node ./node_modules/jest/bin/jest src/tests/fourSlashRunner.test.ts -t "hover\." --forceExit (52 passed)
Ran lint and format checks:
eslint (0 errors), prettier (clean)

Signed-off-by: Vishal Raj <9031842908.vk@gmail.com>
@bschnurr

Copy link
Copy Markdown
Member

🤖 AI-assisted review posted on behalf of Bill Schnurr (@bschnurr)

I found a signature-help regression and an inherited-hover case that still shows an unrelated overload's documentation.

Regression: constructor signature help loses the matching __new__ documentation.

from typing import overload

class NewDocs:
    @overload
    def __init__(self, x: int) -> None: ...
    @overload
    def __init__(self, x: str) -> None: ...
    def __init__(self, x: int | str) -> None: pass

    @overload
    def __new__(cls, x: int) -> "NewDocs":
        """new integer docs"""
    @overload
    def __new__(cls, x: str) -> "NewDocs":
        """new string docs"""
    def __new__(cls, x: int | str) -> "NewDocs":
        return super().__new__(cls)

NewDocs(1)  # Request signature help at the argument.

On 8daba0c7, the active (x: int) signature includes new integer docs; on 74cdebfda, it has no documentation, although hover still shows the matching __new__ documentation. Here signature help supplies an __init__ overload as the hint, but the new guard suppresses the __new__ overloads merely because that hint is nonempty.

Existing gap: inherited overloads can still supply the wrong documentation.

from typing import overload

class Base:
    @overload
    def method(self, x: int) -> int:
        """integer docs"""
    @overload
    def method(self, x: str) -> str: ...
    def method(self, x: int | str) -> int | str:
        return x

class Derived(Base):
    @overload
    def method(self, x: int) -> int: ...
    @overload
    def method(self, x: str) -> str: ...
    def method(self, x: int | str) -> int | str:
        return x

Derived().method("")  # Hover over method.

Both revisions show integer docs for the matched str overload. Base-class resolution calls _selectMemberDocInfo without the matched hint, so the first sibling is still used.

Could the guard distinguish hints from a different constructor member, and avoid borrowing an unrelated inherited overload? Focused signature-help and inherited-hover tests would cover both paths.

…d overload

- Scope memberName check so hints from a different constructor member do not suppress fallback overloads
- Forward matched overload hint in base class resolution to avoid borrowing unrelated inherited sibling overloads
- Add focused FourSlash tests for constructor signature help and inherited method hover

Signed-off-by: Vishal Raj <9031842908.vk@gmail.com>
@vishalrajofficial

Copy link
Copy Markdown
Author

Thanks for the thorough review and edge cases Bill Schnurr (@bschnurr)!

I have addressed both issues in commit b12aabf:

  1. Constructor signature help with __new__ docstrings:

    • Scoped the Tier 3 guard in _selectMemberDocInfo to check hasMatchedOverloadForMember:
      matchedOverloads.some((matched) => memberName === undefined || matched.shared.name === memberName).
    • When resolving constructor docstrings, an __init__ overload hint will no longer suppress __new__ fallback overloads, preserving matching __new__ documentation during signature help when __init__ is undocumented.
  2. Inherited method overload docstring resolution:

    • Forwarded matchedOverloads to _selectMemberDocInfo during base-class MRO walking in resolveMethodDocInfo.
    • The member-scoped guard now prevents falling back to unrelated inherited sibling overloads (e.g. Derived().method("") matching the undocumented str overload will not borrow the int overload docstring from Base).
  3. Tests:

    • Added signature.constructor.overloadedNew.docstring.fourslash.ts verifying constructor signature help keeps __new__ docstrings.
    • Added hover.inheritedOverload.docstring.fourslash.ts verifying inherited method hover does not borrow unrelated sibling overload documentation.

- Correlate corresponding overload signatures across inheritance and between constructor members (__init__ and __new__) using callable parameter matching

- Only suppress Tier 3 fallback when matchedOverloads is a narrowed subset and matches a member overload, preserving docstring inheritance on uncalled hover and completion

Signed-off-by: Vishal Raj <9031842908.vk@gmail.com>

This branch has not been deployed

No deployments
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

Invalid docstring reporting on hover for overloaded function

2 participants