Skip to content

[Pyrefly][Stack] Show annotated Doc parameter docs on Hover, Signature Help - #5671

Open
kinto0 wants to merge 6 commits into
pyrefly-org:mainfrom
kinto0:export-D132412472
Open

kinto0 wants to merge 6 commits into
pyrefly-org:mainfrom
kinto0:export-D132412472

Conversation

@kinto0

@kinto0 kinto0 commented Nov 16, 2026 •

Copy link
Copy Markdown
Contributor

Top of stack. see each commit message for exported plan.

Differential Revision: D132412472

image image

Summary:
Stack context: match annotated-doc `Doc` and `Annotated` with `SpecialExport` instead of by name (plan: https://artifacts.internalmeta.com/a/1087635754250361).
Plan step: 1, NFC precursor.

- What: add `SpecialExport::from_syntax`, which returns the special export that an expression names without resolving imports: a bare name such as `Final`, or an attribute of a module that defines it, such as `typing.Final`. The `Final`-annotation and `deprecated` checks in exports now use it instead of two copies of the same logic.
- Why: a later diff matches `Annotated` and `Doc` the same way when it records `Doc` parameter ranges, which also happens before bindings exist.

___

landed-with-radar-review

Differential Revision: D132395232
Summary:
Stack context: match annotated-doc `Doc` and `Annotated` with `SpecialExport` instead of by name (plan: https://artifacts.internalmeta.com/a/1087635754250361).
Plan step: 2, NFC precursor.

- What: the code that builds a definition's `DocRanges` from its AST, including the `Annotated[..., Doc("...")]` matcher, moves from `pyrefly_python::docstring` to the new `export::doc_ranges` module as `function_doc_ranges`, `class_doc_ranges`, and `doc_ranges_from_parts`. `DocRanges` keeps its representation and accessors, and `DocRanges::new` takes the parameter ranges directly.
- Why: the next diffs match `Annotated` and `Doc` with `SpecialExport`, which lives in the pyrefly library. `pyrefly_python` cannot depend on it.

___

landed-with-radar-review

Differential Revision: D132395233
…odule

Summary:
Stack context: match annotated-doc `Doc` and `Annotated` with `SpecialExport` instead of by name (plan: https://artifacts.internalmeta.com/a/1087635754250361).
Plan step: 3, test of current behavior.

- What: add a `DocRanges` test where `Annotated` and `Doc` are attributes of an unrelated module, `other.Annotated` and `other.Doc`.
- Why: both are matched by name today, so they are wrongly treated as annotated-doc. The next diff fixes this.

___

landed-with-radar-review

Differential Revision: D132395235
Summary:
Stack context: match annotated-doc `Doc` and `Annotated` with `SpecialExport` instead of by name (plan: https://artifacts.internalmeta.com/a/1087635754250361).
Plan step: 4, fix.

- Problem: `Doc` parameter docs matched `Annotated` and `Doc` by name, so an attribute of any module counted, for example `name: other.Annotated[str, other.Doc("...")]`.
- Fix: add `SpecialExport::Doc`, defined in `typing_extensions` and `annotated_doc`, and match both names with `SpecialExport::from_syntax`, the same rule that exports use for `Final` and `deprecated`. A bare name or an attribute of a module that defines it matches. Imports are not resolved, because `DocRanges` are built before bindings exist.

___

landed-with-radar-review

Reviewed By: samwgoldman

Differential Revision: D132395237
Summary:
Stack context: show the annotated-doc `Doc` text of every parameter in function hover (plan: https://artifacts.internalmeta.com/a/2314372522479036).
Plan step: 1, test of current behavior.

- What: a hover test on a function with `Doc` parameter docs, at its definition and at a call in another module.
- Why: function hover shows the signature and docstring, but no `Doc` text. The next diff fixes this.

Differential Revision: D132412471
Summary:
Stack context: show the annotated-doc `Doc` text of every parameter in function hover (plan: https://artifacts.internalmeta.com/a/2314372522479036).
Plan step: 2, fix.

- What: hover on a function shows the `Doc` text of each documented parameter, after the docstring, in definition order. Each entry uses the existing `**Parameter `name`**` format.
- Why: the `Doc` text showed only in a parameter hover and in signature help. Docstring parameter sections already show in function hover, because they are part of the docstring.
- How: the definition that hover finds already carries the `Doc` ranges, which signature help reads with `DocRanges::parameter_docs`. `HoverValue::parameter_doc` becomes a list, which a parameter hover fills with one entry, as before.

Differential Revision: D132412472
@meta-codesync

meta-codesync Bot commented Nov 16, 2026

Copy link
Copy Markdown
Contributor

@kinto0 has exported this pull request. If you are a Meta employee, you can view the originating Diff in D132412472.

@kinto0 kinto0 changed the title Show annotated-doc parameter docs in function hover [Pyrefly][Stack] Show annotated Doc parameter docs on Hover, Signature Help Nov 16, 2026
@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. ✅

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

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant