Remove support for type comments

[AA-Turner]

Is your feature request related to a problem? Please describe.

Sphinx has supported # type: ... comments in autodoc for several years (#2755, #6984). Recently, we have gained support for .pyi stub files (#7630, #13253, #4824). Type comments are primarily useful for supporting both Python 2 and 3; the former has been end-of-life for over five years. For modern situations where inline annotations aren't acceptable or can't be used (e.g. extension modules), .pyi files can be used.

Describe the solution you'd like

Remove support for parsing type comments in Sphinx.

Describe alternatives you've considered

The status quo.

Additional context

• Support for Python 2/3 "straddling" type hint comments #2755
• Close #2755: autodoc: Support type_comment style annotation #6984
• would close autofunction does not support type comment for class object #7639
• would close autodoc_typehints="description" doesn't fully resolve constructor type hints from type comments #8243 (cc @godlygeek)
• [BUG] PropertyDocumenter does not add annotation from type comment #11277 (cc @picnixz)

[picnixz]

Ideally I don't want to lose this one. I still use type comments for line wrapping reasons and for IDEs patches.

I can understand why we want to remove it but I don't think we need to. One reason is that some people may still use them for their own projects.

I'll try to see if I can close the issues that would be closed otherwise though I can't promise anything as my backlog is quite long.

Now, it's been a while since I checked if the IDE and linters were patched so maybe I don't need them anymore.

[Paebbels]

In many cases an IDE can't figure out what type is returned by complex iterators. Thus a type hint in the code for the iteration variable is needed to assist the IDE and allow for auto completion.

Do you refer to those cases when you write about # type: ... or is it purely about the public interface e.g. of functions and methods?

The example described by me is needed for fluent coding, but not relevant for auto documentation of public interfaces.

Can you please clarify?

---

for node in graph.IterateActiveNodes(predicate=...):   # type: Node
   print(node)

[AA-Turner]

@Paebbels I use PyCharm and have a similar problem, but often adding a line containing only an annotation above the iterator helps, eg in your example node: Node.

However, this wouldn't be affected -- I'm proposing removing the old-style type comment usage where function signatures were declared in a comment on the first line of the body. This is because Python 2 didn't support parameter annotations.

A

[Paebbels]

@AA-Turner thanks for clarification. I never used Python 2.7 with type annotations :)

[jbms]

This seems reasonable to me.