Docstring attached to _some_ TypeAliases ignored.

[mjpieters]

It should be possible to attach documentation to a type alias by adding a docstring on the next line. In practice, this doesn't always work. I am unable to attach documentation to the following types of type aliases:

• Direct aliases without further use of further type hint constructs, such as str or a user-defined class, provided those types have a docstring of their own.
• When using a PEP 593 Annotation, where the annotated type is something in the first category, the docstring is ignored and the docstring of the wrapped (primitive) type is used instead.

Environment data

• Language Server version: v2022.11.10
• OS and version: macOS Monterey (12.5.1)
• Python version (& distribution if applicable, e.g. Anaconda): 3.10.8

Code Snippet

from typing import Annotated, TypeAlias

# setup assignments
arbitrary_annotation = 42
class UserDefinedClassWithDocstring:
    """An arbitrary class"""
class UserDefinedClassWithoutDocstring:
    pass

# cases where docstrings are not honoured
StrAlias: TypeAlias = str
"""A regular type alias for str"""
ClassAlias: TypeAlias = UserDefinedClassWithDocstring
"""A class type alias"""
AnnotatedStr: TypeAlias = Annotated[str, arbitrary_annotation]
"""An annotated type alias referencing str"""

# cases where docstrings are honoured
UnionAlias: TypeAlias = str | int
"""A union type alias for str or int"""
AnnotatedAlias: TypeAlias = Annotated[UnionAlias, arbitrary_annotation]
"""An annotated type alias referencing a union alias"""
UndocumentedClassAlias: TypeAlias = UserDefinedClassWithoutDocstring
"""A class type alias where the original has no docstring"""
AnnotatedUndocumentedClassAlias: TypeAlias = Annotated[
    UserDefinedClassWithoutDocstring, arbitrary_annotation
]
"""An annotated type alias referencing a class with no docstring"""

Repro Steps

1. Create a Python file in Visual Studio Code with the above contents
2. Trigger the hover on each TypeAlias assignment (mousing over, or using ⌘K ⌘I / Ctrl-K Ctrl-I (command Kilo India)) to inspect the docstring

Expected behavior

The docstring to be attached to more cases, if not all cases shown. I can understand there must be trade-offs between showing the aliased type docstring vs. the docstring on the alias, but especially for annotated types, there are many use-cases for annotations that constrain the type further, making it very important that documentation is specific.

E.g. take annotating a string as being hexadecimal, using Predicate()type from theannotated-types` project:

import string
from typing import Annotated, Literal, TypeAlias
from annotated_types import Predicate

HexStr = Annotated[str, Predicate(frozenset(string.hexdigits).issuperset)]
"""A hexadecimal string"""

then I really appreciate it when the hover documentation tells me this, instead of the str docstring.

If this isn't a bug and the choice to ignore a docstring for a type alias is explicit, please document when docstrings do work and when not.

Actual behavior

For all type aliases in the cases where docstrings are not honoured group, the docstring shown is that of the aliased type, here either str or UserDefinedClassWithDocstring.

The type aliases in the second group, cases where docstrings are honoured, the attached docstrings are shown.

[rchiodo]

This was actually fixed in our last prerelease. This issue here: #3402

If you update to 2022.11.11, it should show something like so:

we concat the alias string and the original type's string together now.