Close #2755: autodoc: Support type_comment style annotation

[tk0miya]

Feature or Bugfix

• Feature

Purpose

• refs: Support for Python 2/3 "straddling" type hint comments #2755
• Note: python3.8+ or typed_ast is required to use this feature

[tk0miya]

It's time to merge. I'll merge this after minor fixes.

[tk0miya]

Merged. Thank you for reviewing! @shimizukawa @eric-wieser

[eric-wieser]

What's the purpose of autodoc-before-process-signature here? Did you envisage any use case other than parsing type comments?

It seems like this code would become simpler if you just built the type comment knowledge into sphinx.util.inspect.signature.

[eric-wieser]

Edit: Ah, I see it's to make it opt in. Maybe the extension should be called sphinx.ext.typecomments, and be hooked into at the inspect.signature level?

[tk0miya]

It was added to update the signature of function before processing. The use case of the event are 1) type_comments and 2) .pyi files (refs: #4824). I don't know there are any more use case for the event. But I thought it is simple to separate them from inspect.signature(). What do you think?

In addition, the sphinx.ext.autodoc.type_comment was young during 2.4.x. So I marked it as experimental, and separate it to an independent extension from autodoc not to load by default. But, now it becomes a formal feature since 3.0. So it is a part of autodoc and loaded by default.

[eric-wieser]

But I thought it is simple to separate them from inspect.signature(). What do you think?

What I've found is that you seem to end up having to implement the internals of inspect.signature repeatedly, because every time it visits a function, you need to call the hook before looking at it.

See #7384 for an example of this.

Good point about the .pyi files, I hadn't thought about that. Although perhaps simpler would be a third party module that consumes a .pyi file and applies all the annotations in it, rather than only applying them when requested.

[tk0miya]

Indeed. The autodoc + type_comment + Sphinx's inspect module would be an enhanced version of inspect.signature(). It generates documents for functions (signatures) from living objects and source code. I considered the responsibility of inspect.signature() is to obtain a signature from a living object. And to parse type_comment from source code is not. I don't know this is a best design.
Personally, I don't like to create a complex function having multiple responsibilities. But I'm okay to change the design if your proposal is good :-)

Anyway, the event has been released as stable. So we need to keep it working for a while if we'll mark it deprecated.

About the .pyi files, I still don't take a look in detail. So I can't discuss it well. As you said, it might be better to hook them on loading a target module.