Custom docstring about autodocstring

[NilsJPWerner]

This request is a little difficult to complete. Currently docstring formats are integrated by creating individual classes (like this one) that conform to a base interface so that they can be called transparently by the extension. This makes it pretty easy to add new formats and you are free to create a PR integrating a new type of docstring that might be useful to others. However, it would probably be impossible to have this be a setting, since it involves at least a few dozen lines of code.

I am open to suggestions for how this could be integrated though as I think it could potentially be useful to others.

[yyanruo]

@NilsJPWerner Is there anyway i can set the custom docstring for myself?

[balta2ar]

Yes indeed customizable snippets do not seem like a low-hanging fruit feature. One possible approach is to:

1. utilize some template engine (like Jinja2 in Python but something for TypeScript)
2. add a plugin-specific setting "docstringTemplatesFilename"
3. read and process templates from that file.

I've seen something similar in vim plugins, e.g.: https://github.com/heavenshell/vim-pydocstring/blob/master/template/pydocstring/multi.txt

[luav]

It would be awesome to be able to specify own docstring template in the file like:

"""description

<arg>: type  - arg description

return  res - res description
"""

or in the vscode JSON options as a multi-line string like:

"autoDocstring.docstringFormat": "custom",
"autoDocstring.docstringTemplate": [
"description",
"",
"<arg>: type  - arg description",  // <arg> replaced with the actual argument names
"",
"return  res - res description"
],

Where everything is substituted as it is except the <arg> paragraph, which is duplicated the number of times equal to the actual number of arguments and the actual argument names are substituted.

This is seems to be easily implementable by adding a template: string parameter to the BaseFactory::createDocstring and using the outlined processing instead of the abstract callbacks when that templateparameter is not null (i.e. specified in the VSCode config).

[modelmat]

Yes, I agree. Even something simpler such as autodetecting the formats from a folder; e.g. the different classes are:

src/docstring_factories
-- numpy.ts
-- google.ts
-- sphinx.ts

but the user would be able to specify a custom directory

"autoDocstring.docstringFormatsDirectory" : "/my/custom/directory"

/my/custom/directory/
-- format1.ts
-- awesome.ts

Each one of these could be a file such as

import * as interfaces from '../docstring_parts';
import { BaseFactory } from './base_factory'
import * as vscode from 'vscode';

export class AwesomeFactory extends BaseFactory {
...
}

Furthermore, the factories.ts in the src/docstring_factories could use the following

export * from vs.workspace.getConfiguration("autoDocstring").get("docstringFormatsDirectory");

(not sure if this would actually work, nor if this could be appropriately error handled, but it's an idea that certainly requires less syntax parsing on behalf of the developer)
This could probably provide some security issues too though.

[NilsJPWerner]

Custom templates are now supported in the latest version of the extension. v0.3.0