docstring for function with decorators display the doc for the decorator not the the function

[DonJayamanne]

From @tangorboyz on October 29, 2017 11:25

Environment data

VS Code version: 1.18.0-insider
Python Extension version:
Python Version: 0.7.0
OS and version: Ubuntu 16.04

Actual behavior

When hover over a function with decorators like @properties display the the doc for @properties

Expected behavior

It should only display the doc for the function.
As you can see at picture above, is_authenticated is decorated with @properties. But when hover over on is_authenticated, the doc for @properties is displayed.

Copied from original issue: DonJayamanne/pythonVSCode#1352

[DonJayamanne]

From @tangorboyz on November 2, 2017 5:15

Another info: if we type the object method with decorators, the doc for the decorators is displayed.
However if we access it directly from it's class, the actual doc for that method is displayed. Example
User.is_authenticated(), hovering over would display the doc for the is_authenticated itself.
But if initialize an object of that class like user = User(username='username'), and user.is_authenticated(), would display the doc for @property.

[brettcannon]

I would argue you don't want the original module's docstring and what you want is the docstring that the wrapped function ends up with. functools.wraps will copy the docstring for any well-behaving decorator, but there's also the case where someone may very well want to modify the docstring. Plus you want the docstring of the object you're actually going to use (the wrapping function), not the original function whose semantics are now changed due to the wrapping.

[skilly-lily]

I see a lot of inconsistent behavior with decorators/docstrings/argspecs when using intellisense. functools.wraps seems to prevent consistent failure, but introduces inconsistent intellisense behavior. Loading the same file with the same exact code doesn't guarantee that my intellisense popups will show the same way both times. Behavior is erratic with both simple decorator and decorator factories. Note that I do not see this erratic behavior with the interpreter. The interpreter is consistently providing the correct docstrings, provided that the functools.wraps decorator is being used correctly.

Is it possible to get this issue reopened and reviewed again? My framework requires very heavy use of decorators and decorator factories to prevent duplicate code, and this makes it hard for anyone not already familiar with the API to understand the function calls.

I have included example screenshots, as well as the code for those screenshots.

The following screenshots were very hard to get, I had to close and reopen vscode several times to get the message to show. Based on how many times I messed with it to see the incorrect behavior, I have a suspicion that some kind caching logic may be involved, but as I have not looked at the extension code, I cannot be sure.

Simple decorators

Decorator factories

Sample Code

issue.py.txt

[brettcannon]

@iamtheauthor I can't reproduce this, but since we are working on a new analysis engine to replace Jedi and that's where I suspect the problem is, I'm going to close this for now. If you manage to create a reproducer or the new analysis engine doesn't do the right thing, please let us know.