Repository navigation
Show base class docstring on hover for overrides without one - #5656
Quaden2307 wants to merge 3 commits into
Conversation
stroxler
left a comment
There was a problem hiding this comment.
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.
371afba to
5eed835
Compare
|
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.) |
|
According to mypy_primer, this change doesn't affect type check results on a corpus of open source code. ✅ |
|
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! |
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
|
This pull request has been merged in 46a8399. |
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.
Test Plan
Added two tests:
hover_on_override_without_docstring_shows_base_docstringtests 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_docstringtests the case where the child method does have its own docstring, to make sure the fix did not break the normal case.