Skip to content

Show base class docstring on hover for overrides without one - #5656

Closed
Quaden2307 wants to merge 3 commits into
pyrefly-org:mainfrom
Quaden2307:docstring-hover
Closed

Quaden2307 wants to merge 3 commits into
pyrefly-org:mainfrom
Quaden2307:docstring-hover

Conversation

@Quaden2307

Copy link
Copy Markdown
Contributor

Summary

Fixes #5395

When a method that was overridden was hovered over, if the method had no docstring, the docstring in the base class was not shown. The fix was to add a function that checks the parent classes in order, closest parent first, and uses the first docstring it finds for the hover.

  • I am a human, and I fully understand the code I am submitting.

Test Plan

Added two tests: hover_on_override_without_docstring_shows_base_docstring tests the case when a child method has no docstring, so the hover should show the parent's docstring. hover_on_override_with_docstring_prefers_own_docstring tests the case where the child method does have its own docstring, to make sure the fix did not break the normal case.

@stroxler stroxler left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Hi @Quaden2307, thanks for the PR!

This looks fairly good, but AI review flagged that this fix doesn't appear to preserve the property that stub docstrings, when they exist, should take priority over .py file docstrings on a per-name basis.

Consider:

# lib.py
class Base:
    def f(self) -> None:
        """Base documentation."""

# lib.pyi
class Base:
    def f(self) -> None: ...

# main.py
from lib import Base

class Child(Base):
    def f(self) -> None:
        pass

Child().f()  # Hover on f

Could the inherited lookup reuse the existing stub-to-implementation documentation fallback? Here, Base.f has no docs in lib.pyi, but does in lib.py. The new lookup skips the implementation, so the override still gets no documentation.

The suggested fix is to keep the MRO-ordered list of declarations as you have it here, but use existing logic for the .pyi -> .py fallback.

To understand where the fallback logic exists today, you can take a look at

  • The hover fallback block in get_hover_with_verbosity: prefers nonempty interface (.pyi) documentation, then falls back to executable (.py) documentation.
  • resolve_attribute_definition: already locates the corresponding .py definition when prefer_pyi is false. The new inherited lookup reaches this helper, but its default preference disables that search.

When a method override has no docstring, hover shows the docstring of
the same method in the nearest base class. That lookup only read the
base class's stub, so a base method documented in its .py file but not
in its .pyi stub still showed no documentation.

For each base class, the lookup now tries the stub first and then the
matching .py definition, and keeps the first nonempty docstring. This
is the same stub-first order that hover already uses for a symbol's own
documentation, so a stub docstring still wins whenever it exists.
@meta-codesync

meta-codesync Bot commented Nov 18, 2026

Copy link
Copy Markdown
Contributor

This pull request has been imported. If you are a Meta employee, you can view this in D132750953. (Because this pull request was imported automatically, there will not be any future comments.)

@github-actions

Copy link
Copy Markdown

According to mypy_primer, this change doesn't affect type check results on a corpus of open source code. ✅

@Quaden2307

Copy link
Copy Markdown
Contributor Author

Thanks for the feedback! The lookup now reuses the existing stub-to-implementation fallback. I added your example as a test and rebased onto main to fix the merge conflict. Let me know if you want more changes!

@meta-codesync meta-codesync Bot closed this in 46a8399 Nov 18, 2026
meta-codesync Bot pushed a commit that referenced this pull request Nov 18, 2026
Summary:
The inherited method docstring fallback for hover (#5656) has three known problems, which these tests record:

- In a diamond hierarchy, it shows the docstring of a base that comes after a closer documented base in the MRO.
- It applies to any name whose value is a method, so a class field bound to a method hides its own field docstring, and a variable bound to a method borrows the base method docstring.
- It treats a private (name-mangled) method as an override of the base method with the same name.

The following commits fix these and update the expectations.

___

landed-with-radar-review

Differential Revision: D132958649

fbshipit-source-id: 671d2d985e70f04c8463c9312244de52162c0fe0
@meta-codesync meta-codesync Bot added the Merged label Nov 18, 2026
@meta-codesync

meta-codesync Bot commented Nov 18, 2026

Copy link
Copy Markdown
Contributor

This pull request has been merged in 46a8399.

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

Projects

None yet

Development

Successfully merging this pull request may close these issues.

Inherit base method docstrings in hover when an override has no docstring

2 participants