Aim

I found a bug (reported in #143 ) where if you have some commented out sentence that contains the word "raise" would cause it to be parsed as if it was an Exception leading to this strange behaviour:

def foo(bar):
    """[summary]

    Args:
        bar ([type]): [description]

    Raises:
        appropriate: [description]
    """
	print('Hello World')
	# TODO: raise appropriate error down the line

I modified the regex pattern to ignore raise if a "#" came at any point before it.

How was this tested

Ran the example snippet provided above with expected behaviour. Ran it also with a good old Exception to see if I didn't just break the functionality all together npn run test & npm run integration_test

I didn't add a test to cover this particular case (I figured better to leave the current test be simple), but if you feel strongly about it I could!

Related Issue

Fixes #143

Describe the bug The doc string template is not generated below the function def after entering """. This was working a few days ago, I noticed an update today, April 21, 2020 was pushed.
I reverted to version 0.4.0 and then it worked as expected.

Versions (please complete the following information):

• autoDocstring Version: 0.5.0
• Operating System: Windows 10, version 2004
• Vscode Version: 1.44.2

Original Code (with line to generate on):

def single_slug(request, single_slug):
    categories = [c.category_slug for c in TutorialCategory.objects.all()]

Expected Result:

Actual Result:

def single_slug(request, single_slug):
    """
    
    categories = [c.category_slug for c in TutorialCategory.objects.all()]

Additional context Add any other context about the problem here.

Hi, there. I am wondering is there a way to remove the square brackets used in this extension?

When I want to edit the comments like ''[Type]'' and ''[description]'', it is a little annoying that I can not quick select the whole word with the brackets. I know there is a hot key 'Tab', but it seems just works at the first time when I create the snippets. I'd like to remove the square brackets so that I can re-edit the strings.

Description

As explained in #138 the ability to guess types from type hints was "broken" when it would encounter a quoted type hint as in the example below:

from typing import TYPE_CHECKING

if TYPE_CHECKING:
	import pandas as pd

def foo(bar: "pd.DataFrame"):
	pass

Since quoted type hints aren't uncommon when the developer does not want to import a library and in the case of forward imports. I thought this might be a nice addition.

Without an ability to parse quoted hints, the docstring would fail to generate arguments with types resulting in the following:

def foo(bar: "pd.DataFrame"):
	"""[summary]
	"""

How was this tested?

• Ran ext in VSCode extention development. Tested the following cases" def foo(bar: pd.DataFrame):, def foo(bar: "pd.DataFrame"):, def foo(bar: 'pd.DataFrame'): All lead to:

def foo(bar: "pd.DataFrame", is_something):
    """[summary]

    Args:
        bar (pd.DataFrame): [description]
        is_something: (bool): [description]
    """

Note to reviewer

I didn't check other functionalities nor ran unit tests to check this change wasn't breaking anything as I'm not great at working in TypeScript or developing extensions in VSCode, but would be happy to run further tests on your guidance if required.

Also, I haven't checked whether there are any PEP conventions that would advise against documenting hints that are quoted, but I don't see why not.

Related Issue

Fixes #138

Autodocstring shows errors when I show running extensions in VSCode:

• Issue Type: Bug
• Extension Name: autodocstring
• Extension Version: 0.4.0
• OS Version: Windows_NT x64 10.0.18362
• VSCode version: 1.41.1

{
	"messages": [],
	"activationTimes": {
		"codeLoadingTime": 226,
		"activateCallTime": 0,
		"activateResolvedTime": 922,
		"activationReason": {
			"startup": false,
			"extensionId": {
				"value": "njpwerner.autodocstring",
				"_lower": "njpwerner.autodocstring"
			},
			"activationEvent": "onLanguage:python"
		}
	},
	"runtimeErrors": [
		{
			"name": "Error",
			"message": "Illegal argument: character must be non-negative"
		},
		{
			"name": "Error",
			"message": "Illegal argument: character must be non-negative"
		},
		{
			"name": "Error",
			"message": "Illegal argument: character must be non-negative"
		},
		{
			"name": "Error",
			"message": "Illegal argument: character must be non-negative"
		},
		{
			"name": "Error",
			"message": "Illegal argument: character must be non-negative"
		},
		{
			"name": "Error",
			"message": "Illegal argument: character must be non-negative"
		},
		{
			"name": "TypeError",
			"message": "Cannot read property 'document' of undefined"
		},
		{
			"name": "TypeError",
			"message": "Cannot read property 'document' of undefined"
		},
		{
			"name": "Error",
			"message": "Illegal argument: character must be non-negative"
		},
		{
			"name": "Error",
			"message": "Illegal argument: character must be non-negative"
		},
		{
			"name": "Error",
			"message": "Illegal argument: character must be non-negative"
		},
		{
			"name": "TypeError",
			"message": "Cannot read property 'document' of undefined"
		},
		{
			"name": "TypeError",
			"message": "Cannot read property 'document' of undefined"
		},
		{
			"name": "TypeError",
			"message": "Cannot read property 'document' of undefined"
		},
		{
			"name": "TypeError",
			"message": "Cannot read property 'document' of undefined"
		},
		{
			"name": "TypeError",
			"message": "Cannot read property 'document' of undefined"
		},
		{
			"name": "Error",
			"message": "Illegal argument: character must be non-negative"
		},
		{
			"name": "Error",
			"message": "Illegal argument: character must be non-negative"
		},
		{
			"name": "Error",
			"message": "Illegal argument: character must be non-negative"
		},
		{
			"name": "Error",
			"message": "Illegal argument: character must be non-negative"
		},
		{
			"name": "Error",
			"message": "Illegal argument: character must be non-negative"
		},
		{
			"name": "Error",
			"message": "Illegal argument: character must be non-negative"
		},
		{
			"name": "Error",
			"message": "Illegal argument: character must be non-negative"
		},
		{
			"name": "Error",
			"message": "Illegal argument: character must be non-negative"
		},
		{
			"name": "Error",
			"message": "Illegal argument: character must be non-negative"
		},
		{
			"name": "TypeError",
			"message": "Cannot read property 'document' of undefined"
		},
		{
			"name": "Error",
			"message": "Illegal argument: character must be non-negative"
		},
		{
			"name": "Error",
			"message": "Illegal argument: character must be non-negative"
		},
		{
			"name": "Error",
			"message": "Illegal argument: character must be non-negative"
		},
		{
			"name": "Error",
			"message": "Illegal argument: character must be non-negative"
		},
		{
			"name": "Error",
			"message": "Illegal argument: character must be non-negative"
		},
		{
			"name": "Error",
			"message": "Illegal argument: character must be non-negative"
		},
		{
			"name": "Error",
			"message": "Illegal argument: character must be non-negative"
		},
		{
			"name": "Error",
			"message": "Illegal argument: character must be non-negative"
		},
		{
			"name": "Error",
			"message": "Illegal argument: character must be non-negative"
		},
		{
			"name": "Error",
			"message": "Illegal argument: character must be non-negative"
		},
		{
			"name": "Error",
			"message": "Illegal argument: character must be non-negative"
		},
		{
			"name": "Error",
			"message": "Illegal argument: character must be non-negative"
		}
	]
}

auto docstring works fine locally, but on remote-ssh docstrings are not generated:

command 'extension.generateDocstring' not found

uninstalling and reinstalling did not work, nor did installing remotely.

Windows 10 vscode 1.27.2

 ERR Cannot read property 'document' of undefined: TypeError: Cannot read property 'document' of undefined
	at activateOnEnter (C:\Users\almenon\.vscode\extensions\njpwerner.autodocstring-0.2.3\out\src\extension.js:19:36)
	at context.subscriptions.push.vs.workspace.onDidChangeTextDocument.changeEvent (C:\Users\almenon\.vscode\extensions\njpwerner.autodocstring-0.2.3\out\src\extension.js:13:90)
	at e.fire (c:\Program Files\Microsoft VS Code\resources\app\out\vs\workbench\node\extensionHostProcess.js:99:917)
	at e.$acceptModelChanged (c:\Program Files\Microsoft VS Code\resources\app\out\vs\workbench\node\extensionHostProcess.js:742:362)
	at e._doInvokeHandler (c:\Program Files\Microsoft VS Code\resources\app\out\vs\workbench\node\extensionHostProcess.js:681:309)
	at e._invokeHandler (c:\Program Files\Microsoft VS Code\resources\app\out\vs\workbench\node\extensionHostProcess.js:681:27)
	at e._receiveRequest (c:\Program Files\Microsoft VS Code\resources\app\out\vs\workbench\node\extensionHostProcess.js:679:802)
	at e._receiveOneMessage (c:\Program Files\Microsoft VS Code\resources\app\out\vs\workbench\node\extensionHostProcess.js:678:993)
	at c:\Program Files\Microsoft VS Code\resources\app\out\vs\workbench\node\extensionHostProcess.js:677:791
	at c:\Program Files\Microsoft VS Code\resources\app\out\vs\workbench\node\extensionHostProcess.js:98:597
	at e.fire (c:\Program Files\Microsoft VS Code\resources\app\out\vs\workbench\node\extensionHostProcess.js:99:917)
	at a (c:\Program Files\Microsoft VS Code\resources\app\out\vs\workbench\node\extensionHostProcess.js:164:787)
	at Socket.n._socketDataListener (c:\Program Files\Microsoft VS Code\resources\app\out\vs\workbench\node\extensionHostProcess.js:164:1006)
	at emitOne (events.js:116:13)
	at Socket.emit (events.js:211:7)
	at addChunk (_stream_readable.js:263:12)
	at readableAddChunk (_stream_readable.js:250:11)
	at Socket.Readable.push (_stream_readable.js:208:10)
	at Pipe.onread (net.js:594:20)

Full docstring is generated normally, with types inferred from hints.

def fun(a1: str, a2: dict) -> str:
    """[summary]

    :param a1: [description]
    :type a1: str
    :param a2: [description]
    :type a2: dict
    :return: [description]
    :rtype: str
    """
    pass

But if there is a comment after function definition in the same logical line (it may contain physical line breaks) only summary field is generated:

def fun(a1: str, a2: dict) -> str:  # comment
    """[summary]
    """
    pass

This is usual place for code analysis tools to put pragmas, like pragma: nocover to skip block from test coverage calculation.

This works as the quoteStyle is passed from where it is detected in baseFactory throughout all the commands which detect the docstring opener and quotes. These include

• validEnterActivation
• docstringIsClosed
• isMultiString
• contentText

I haven't properly updated the unit testing to test for ''' quotes, as it is a very tedious operation that I didn't feel like doing.

This fixes #49

Hi there, great extension! I'm wondering if you'd be willing to add an option which completely disables the generation of type information inside the generated docstrings. I only have experience with sphinx, so I'm not sure how the other docstring types would look, but since my code is using type annotations I tend to write my docstrings like this:

def foo(some_param: str) -> int:
    """Some function.
    
    :param some_param: the thing that does the other thing
    :return: some meaning of life or whatever
    """
    return 42

(omitting the types entirely, since it's possible to generate the sphinx docs using a plugin such as https://pypi.org/project/sphinx-autodoc-annotation/ or https://github.com/agronholm/sphinx-autodoc-typehints).

Happy to help with a PR if you're ok with the idea (although, I'd probably need to research if the other docstring types work without type information).

feature request

Consider adding a feature to create custom docstring formats that can be used as user settings. It would be quite useful when there is need to maintain a specific coding style across a project.

Description when a certain exception is raised on multiple lines within the function, the exception will occur multiple times in the docstring.

Versions:

• autoDocstring Version: v0.6.1
• Operating System: Win 10
• Vscode Version: 1.73.0

Original Code

def TestFxn(arg0: int, arg1: str) -> str:
        if len(arg1) * arg0 > 1000:
            raise ValueError("bad idea... too many chars")
        if not arg1:
            raise ValueError("empty string")

        return arg1 * arg0

Expected Result:

def TestFxn(arg0: int, arg1: str) -> str:
        """_summary_

        Args:
            arg0 (int): _description_
            arg1 (str): _description_

        Raises:
            ValueError: _description_

        Returns:
            str: _description_
        """

Actual Result:

def TestFxn(arg0: int, arg1: str) -> str:
        """_summary_

        Args:
            arg0 (int): _description_
            arg1 (str): _description_

        Raises:
            ValueError: _description_
            ValueError: _description_

        Returns:
            str: _description_
        """

I have had the occasion to write python code inside another type of source file. autoDocstring seems only to be enabled for source files with a .py extension. It would be great to be able to specify a list of types in settings.json that would allow other types of files to take advantage of autoDocstring.

Describe the bug If the return type has a nested forward reference (e.g. -> Iterable["ForwardRef"]), then the whole parameters/args block and return block in the docstring will be omitted. Note: If the whole return type is made a forward reference (e.g. -> "Iterable[ForwardRef]"), or if the partial forward ref is only on a function argument then this does not occur.

Versions (please complete the following information):

• autoDocstring Version: v0.6.1
• Operating System: Windows 10 x64
• Vscode Version: 1.73.0

Original Code (with line to generate on):

from typing import Iterable

def test_func(value: "str") -> Iterable["str"]:
    # generate on this line    
    pass

Expected Result:

def test_func(value: "str") -> "Iterable[str]":
    """_summary_

    Parameters
    ----------
    value : str
        _description_

    Returns
    -------
    Iterable[str]
        _description_
    """    
    pass

Actual Result:

def test_func(value: "str") -> Iterable["str"]:
    """_summary_
    """    
    pass

Debug log: Set autoDocstring.logLevel to "Debug", recreate the bug, and then copy the debug logs from the autoDocstring output channel.

[INFO 09:27:50.018] Generating Docstring at line: 3
[INFO 09:27:50.022] Docstring generated:
    """${1:_summary_}
    """
[INFO 09:27:50.022] Inserting at position: 3 0
[INFO 09:27:50.050] Successfully inserted docstring

Stack trace: If an error was reported by autoDocstring please copy the stack trace from the autoDocstring output channel.

Additional context Add any other context about the problem here.

Describe the bug Generate docstring encounters error on use

Versions (please complete the following information):

• autoDocstring Version:
• Operating System: arch-manjaro
• Vscode Version: september-22

Original Code (with line to generate on):

# generate on this line

Expected Result:

Actual Result:

Debug log: [INFO 15:24:07.018] ai-docstring was activated [INFO 15:25:54.154] Generating Docstring at line: 99 [INFO 15:25:54.160] Docstring generated: """ add_links_to_tagfiles ${1:AI is creating summary for add_links_to_tagfiles}

${2:[extended_summary]}
"""

[INFO 15:25:54.160] Inserting at position: 99 0 [INFO 15:25:54.208] Successfully inserted docstring [ERROR 15:25:54.237] Error: connect ECONNREFUSED 127.0.0.1:5000

Stack trace: If an error was reported by autoDocstring please copy the stack trace from the autoDocstring output channel.

Additional context Used to work, fresh install.

Describe the bug Not working properly for class documentation, should add init args & *kwargs to class docstring instead of treating base class as arguments

Versions (please complete the following information):

• autoDocstring Version:0.6.2 (tried with earlier versions as well)
• Operating System:Mac OS Monterey
• Vscode Version:1.72.1

Original Code (with line to generate on):

class A(SuperA, SuperB, SuperC):
    def __init__(apple, bat, cat=None):
        pass

Expected Result:

class A(SuperA, SuperB, SuperC):
	"""_summary_

	:param apple: _description_
	:param bat: _description_
	:param cat: _description_, defaults to None
	"""
	def __init__(apple, bat, cat=None):
		pass

Actual Result:

class A(SuperA, SuperB, SuperC):
	"""_summary_

	:param SuperA: _description_
	:param SuperB: _description_
	:param SuperC: _description_
	"""
    def __init__(apple, bat, cat=None):
        pass

Debug log: Set autoDocstring.logLevel to "Debug", recreate the bug, and then copy the debug logs from the autoDocstring output channel.

[INFO 23:37:46.255] Generating Docstring at line: 16
[INFO 23:37:46.257] Docstring generated:
	"""${1:_summary_}

	:param SuperA: ${2:_description_}
	:param SuperB: ${3:_description_}
	:param SuperC: ${4:_description_}
	"""
[INFO 23:37:46.257] Inserting at position: 16 0
[INFO 23:37:46.263] Successfully inserted docstring

Stack trace: If an error was reported by autoDocstring please copy the stack trace from the autoDocstring output channel.

Additional context Add any other context about the problem here.

Describe the bug Right now we have to put cursor below the function definition and then press enter and then generate the docstring. The best way is that wherever on the function definition or in the function body we are, if we press shortcut key (e.g., ctrl+shift+2) it should automatically generate the docString in the right place.