Eslint-plugin-jsdoc: [function-rules] Allow function-rules such as `require-param` for typescript
In https://github.com/gajus/eslint-plugin-jsdoc/issues/511 I've noticed that some sort of rules such as require-param don't work for some sort of method-definitions.
Therefore I'm going to post any kind of method that could appear in TypeScript.
Is there some way I could help you implementing TS method support?
All the test btw. have been made using the require-param rule.
Non-Implemented Method-Types
❎ Abstract Class-Method (not implemented yet)
Though the TSEmptyBodyFunctionExpression looks exactly the same like other function-contexts, adding this to the contexts-array of the require-param doesn't work.
/**
* A test class.
*/
abstract class TestClass
{
/**
* A test method.
*
* @param id
* A test-id.
*/
abstract TestFunction(id);
}
Parsed
{
"type": "Program",
"body": [
{
"type": "ClassDeclaration",
"id": {
"type": "Identifier",
"name": "TestClass",
"range": [
43,
52
],
"loc": {
"start": {
"line": 4,
"column": 15
},
"end": {
"line": 4,
"column": 24
}
}
},
"body": {
"type": "ClassBody",
"body": [
{
"type": "TSAbstractMethodDefinition",
"key": {
"type": "Identifier",
"name": "TestFunction",
"range": [
156,
168
],
"loc": {
"start": {
"line": 12,
"column": 13
},
"end": {
"line": 12,
"column": 25
}
}
},
"value": {
"type": "TSEmptyBodyFunctionExpression",
"id": null,
"generator": false,
"expression": false,
"async": false,
"body": null,
"range": [
168,
173
],
"params": [
{
"type": "Identifier",
"name": "id",
"range": [
169,
171
],
"loc": {
"start": {
"line": 12,
"column": 26
},
"end": {
"line": 12,
"column": 28
}
}
}
],
"loc": {
"start": {
"line": 12,
"column": 25
},
"end": {
"line": 12,
"column": 30
}
}
},
"computed": false,
"static": false,
"kind": "method",
"range": [
147,
173
],
"loc": {
"start": {
"line": 12,
"column": 4
},
"end": {
"line": 12,
"column": 30
}
}
}
],
"range": [
54,
176
],
"loc": {
"start": {
"line": 5,
"column": 0
},
"end": {
"line": 13,
"column": 1
}
}
},
"superClass": null,
"range": [
28,
176
],
"loc": {
"start": {
"line": 4,
"column": 0
},
"end": {
"line": 13,
"column": 1
}
},
"abstract": true
}
],
"sourceType": "module",
"range": [
28,
178
],
"loc": {
"start": {
"line": 4,
"column": 0
},
"end": {
"line": 14,
"column": 0
}
}
}
❎ Function-Type declaration (not implemented yet)
The context for function-types is TSFunctionType and though this context has properties like params etc. adding this to the contexts-array doesn't work.
Works by checking the ``-context
/**
* A test function.
*
* @param id
* A test id.
*/
declare let TestFunction: (id) => void;
Parsed
{
"type": "Program",
"body": [
{
"type": "VariableDeclaration",
"declarations": [
{
"type": "VariableDeclarator",
"id": {
"type": "Identifier",
"name": "TestFunction",
"range": [
76,
102
],
"loc": {
"start": {
"line": 7,
"column": 12
},
"end": {
"line": 7,
"column": 38
}
},
"typeAnnotation": {
"type": "TSTypeAnnotation",
"loc": {
"start": {
"line": 7,
"column": 24
},
"end": {
"line": 7,
"column": 38
}
},
"range": [
88,
102
],
"typeAnnotation": {
"type": "TSFunctionType",
"params": [
{
"type": "Identifier",
"name": "id",
"range": [
91,
93
],
"loc": {
"start": {
"line": 7,
"column": 27
},
"end": {
"line": 7,
"column": 29
}
}
}
],
"range": [
90,
102
],
"loc": {
"start": {
"line": 7,
"column": 26
},
"end": {
"line": 7,
"column": 38
}
},
"returnType": {
"type": "TSTypeAnnotation",
"loc": {
"start": {
"line": 7,
"column": 31
},
"end": {
"line": 7,
"column": 38
}
},
"range": [
95,
102
],
"typeAnnotation": {
"type": "TSVoidKeyword",
"range": [
98,
102
],
"loc": {
"start": {
"line": 7,
"column": 34
},
"end": {
"line": 7,
"column": 38
}
}
}
}
}
}
},
"init": null,
"range": [
76,
102
],
"loc": {
"start": {
"line": 7,
"column": 12
},
"end": {
"line": 7,
"column": 38
}
}
}
],
"kind": "let",
"range": [
64,
103
],
"loc": {
"start": {
"line": 7,
"column": 0
},
"end": {
"line": 7,
"column": 39
}
},
"declare": true
}
],
"sourceType": "module",
"range": [
64,
105
],
"loc": {
"start": {
"line": 7,
"column": 0
},
"end": {
"line": 8,
"column": 0
}
}
}
❎ Declared Method Type
Just like for abstract methods here the context seems to be TSEmptyBodyFunctionExpression, too. Adding this to the contexts-array doesn't work though.
/**
* A test class.
*/
declare class TestClass
{
TestMethod(id);
}
Parsed
{
"type": "Program",
"body": [
{
"type": "ClassDeclaration",
"id": {
"type": "Identifier",
"name": "TestClass",
"range": [
42,
51
],
"loc": {
"start": {
"line": 4,
"column": 14
},
"end": {
"line": 4,
"column": 23
}
}
},
"body": {
"type": "ClassBody",
"body": [
{
"type": "MethodDefinition",
"key": {
"type": "Identifier",
"name": "TestMethod",
"range": [
60,
70
],
"loc": {
"start": {
"line": 6,
"column": 4
},
"end": {
"line": 6,
"column": 14
}
}
},
"value": {
"type": "TSEmptyBodyFunctionExpression",
"id": null,
"generator": false,
"expression": false,
"async": false,
"body": null,
"range": [
70,
75
],
"params": [
{
"type": "Identifier",
"name": "id",
"range": [
71,
73
],
"loc": {
"start": {
"line": 6,
"column": 15
},
"end": {
"line": 6,
"column": 17
}
}
}
],
"loc": {
"start": {
"line": 6,
"column": 14
},
"end": {
"line": 6,
"column": 19
}
}
},
"computed": false,
"static": false,
"kind": "method",
"range": [
60,
75
],
"loc": {
"start": {
"line": 6,
"column": 4
},
"end": {
"line": 6,
"column": 19
}
}
}
],
"range": [
53,
78
],
"loc": {
"start": {
"line": 5,
"column": 0
},
"end": {
"line": 7,
"column": 1
}
}
},
"superClass": null,
"range": [
28,
78
],
"loc": {
"start": {
"line": 4,
"column": 0
},
"end": {
"line": 7,
"column": 1
}
},
"declare": true
}
],
"sourceType": "module",
"range": [
28,
80
],
"loc": {
"start": {
"line": 4,
"column": 0
},
"end": {
"line": 8,
"column": 0
}
}
}
Implemented Method-Types
✅ Function (already implemented)
Works by checking the FunctionDeclaration-context.
/**
* Test.
*
* @param id
* A test ID.
*/
function TestFunction(id) { }
Parsed
{
"type": "Program",
"body": [
{
"type": "FunctionDeclaration",
"id": {
"type": "Identifier",
"name": "TestFunction",
"range": [
62,
74
],
"loc": {
"start": {
"line": 7,
"column": 9
},
"end": {
"line": 7,
"column": 21
}
}
},
"generator": false,
"expression": false,
"async": false,
"params": [
{
"type": "Identifier",
"name": "id",
"range": [
75,
77
],
"loc": {
"start": {
"line": 7,
"column": 22
},
"end": {
"line": 7,
"column": 24
}
}
}
],
"body": {
"type": "BlockStatement",
"body": [],
"range": [
79,
82
],
"loc": {
"start": {
"line": 7,
"column": 26
},
"end": {
"line": 7,
"column": 29
}
}
},
"range": [
53,
82
],
"loc": {
"start": {
"line": 7,
"column": 0
},
"end": {
"line": 7,
"column": 29
}
}
}
],
"sourceType": "module",
"range": [
53,
82
],
"loc": {
"start": {
"line": 7,
"column": 0
},
"end": {
"line": 7,
"column": 29
}
}
}
✅ Arrow-Function (already implemented)
Works by checking the ArrowFunctionExpression-context.
/**
* Test.
*
* @param id
* A test ID.
*/
let TestFunction = (id) => { }
Parsed
{
"type": "Program",
"body": [
{
"type": "VariableDeclaration",
"declarations": [
{
"type": "VariableDeclarator",
"id": {
"type": "Identifier",
"name": "TestFunction",
"range": [
57,
69
],
"loc": {
"start": {
"line": 7,
"column": 4
},
"end": {
"line": 7,
"column": 16
}
}
},
"init": {
"type": "ArrowFunctionExpression",
"generator": false,
"id": null,
"params": [
{
"type": "Identifier",
"name": "id",
"range": [
73,
75
],
"loc": {
"start": {
"line": 7,
"column": 20
},
"end": {
"line": 7,
"column": 22
}
}
}
],
"body": {
"type": "BlockStatement",
"body": [],
"range": [
80,
83
],
"loc": {
"start": {
"line": 7,
"column": 27
},
"end": {
"line": 7,
"column": 30
}
}
},
"async": false,
"expression": false,
"range": [
72,
83
],
"loc": {
"start": {
"line": 7,
"column": 19
},
"end": {
"line": 7,
"column": 30
}
}
},
"range": [
57,
83
],
"loc": {
"start": {
"line": 7,
"column": 4
},
"end": {
"line": 7,
"column": 30
}
}
}
],
"kind": "let",
"range": [
53,
83
],
"loc": {
"start": {
"line": 7,
"column": 0
},
"end": {
"line": 7,
"column": 30
}
}
}
],
"sourceType": "module",
"range": [
53,
85
],
"loc": {
"start": {
"line": 7,
"column": 0
},
"end": {
"line": 8,
"column": 0
}
}
}
✅ Class Method (already implemented)
Works by checking the FunctionExpression-context.
/**
* A test class.
*/
class TestClass
{
TestFunction(id) { }
}
Parsed
{
"type": "Program",
"body": [
{
"type": "ClassDeclaration",
"id": {
"type": "Identifier",
"name": "TestClass",
"range": [
34,
43
],
"loc": {
"start": {
"line": 4,
"column": 6
},
"end": {
"line": 4,
"column": 15
}
}
},
"body": {
"type": "ClassBody",
"body": [
{
"type": "MethodDefinition",
"key": {
"type": "Identifier",
"name": "TestFunction",
"range": [
52,
64
],
"loc": {
"start": {
"line": 6,
"column": 4
},
"end": {
"line": 6,
"column": 16
}
}
},
"value": {
"type": "FunctionExpression",
"id": null,
"generator": false,
"expression": false,
"async": false,
"body": {
"type": "BlockStatement",
"body": [],
"range": [
69,
72
],
"loc": {
"start": {
"line": 6,
"column": 21
},
"end": {
"line": 6,
"column": 24
}
}
},
"range": [
64,
72
],
"params": [
{
"type": "Identifier",
"name": "id",
"range": [
65,
67
],
"loc": {
"start": {
"line": 6,
"column": 17
},
"end": {
"line": 6,
"column": 19
}
}
}
],
"loc": {
"start": {
"line": 6,
"column": 16
},
"end": {
"line": 6,
"column": 24
}
}
},
"computed": false,
"static": false,
"kind": "method",
"range": [
52,
72
],
"loc": {
"start": {
"line": 6,
"column": 4
},
"end": {
"line": 6,
"column": 24
}
}
}
],
"range": [
45,
75
],
"loc": {
"start": {
"line": 5,
"column": 0
},
"end": {
"line": 7,
"column": 1
}
}
},
"superClass": null,
"range": [
28,
75
],
"loc": {
"start": {
"line": 4,
"column": 0
},
"end": {
"line": 7,
"column": 1
}
}
}
],
"sourceType": "module",
"range": [
28,
77
],
"loc": {
"start": {
"line": 4,
"column": 0
},
"end": {
"line": 8,
"column": 0
}
}
}
✅ Interface-Method (already implemented)
Works by checking the TSMethodSignature-context.
/**
* A test interface.
*/
interface TestInterface
{
/**
* A test method.
*
* @param id
* A test id.
*/
TestMethod(id);
}
Parsed
{
"type": "Program",
"body": [
{
"type": "TSInterfaceDeclaration",
"body": {
"type": "TSInterfaceBody",
"body": [
{
"type": "TSMethodSignature",
"computed": false,
"key": {
"type": "Identifier",
"name": "TestMethod",
"range": [
150,
160
],
"loc": {
"start": {
"line": 12,
"column": 4
},
"end": {
"line": 12,
"column": 14
}
}
},
"params": [
{
"type": "Identifier",
"name": "id",
"range": [
161,
163
],
"loc": {
"start": {
"line": 12,
"column": 15
},
"end": {
"line": 12,
"column": 17
}
}
}
],
"range": [
150,
165
],
"loc": {
"start": {
"line": 12,
"column": 4
},
"end": {
"line": 12,
"column": 19
}
}
}
],
"range": [
57,
168
],
"loc": {
"start": {
"line": 5,
"column": 0
},
"end": {
"line": 13,
"column": 1
}
}
},
"id": {
"type": "Identifier",
"name": "TestInterface",
"range": [
42,
55
],
"loc": {
"start": {
"line": 4,
"column": 10
},
"end": {
"line": 4,
"column": 23
}
}
},
"range": [
32,
168
],
"loc": {
"start": {
"line": 4,
"column": 0
},
"end": {
"line": 13,
"column": 1
}
}
}
],
"sourceType": "module",
"range": [
32,
170
],
"loc": {
"start": {
"line": 4,
"column": 0
},
"end": {
"line": 14,
"column": 0
}
}
}
✅ Type-Members (already implemented)
Works by checking the TSMethodSignature-context.
/**
* A test type.
*/
type TestType = {
/**
* A test method.
*/
TestMethod(id);
}
Parsed
{
"type": "Program",
"body": [
{
"type": "TSTypeAliasDeclaration",
"id": {
"type": "Identifier",
"name": "TestType",
"range": [
32,
40
],
"loc": {
"start": {
"line": 4,
"column": 5
},
"end": {
"line": 4,
"column": 13
}
}
},
"typeAnnotation": {
"type": "TSTypeLiteral",
"members": [
{
"type": "TSMethodSignature",
"computed": false,
"key": {
"type": "Identifier",
"name": "TestMethod",
"range": [
91,
101
],
"loc": {
"start": {
"line": 8,
"column": 4
},
"end": {
"line": 8,
"column": 14
}
}
},
"params": [
{
"type": "Identifier",
"name": "id",
"range": [
102,
104
],
"loc": {
"start": {
"line": 8,
"column": 15
},
"end": {
"line": 8,
"column": 17
}
}
}
],
"range": [
91,
106
],
"loc": {
"start": {
"line": 8,
"column": 4
},
"end": {
"line": 8,
"column": 19
}
}
}
],
"range": [
43,
109
],
"loc": {
"start": {
"line": 4,
"column": 16
},
"end": {
"line": 9,
"column": 1
}
}
},
"range": [
27,
109
],
"loc": {
"start": {
"line": 4,
"column": 0
},
"end": {
"line": 9,
"column": 1
}
}
}
],
"sourceType": "module",
"range": [
27,
111
],
"loc": {
"start": {
"line": 4,
"column": 0
},
"end": {
"line": 10,
"column": 0
}
}
}
✅ Declared function
Works by checking the TSDeclareFunction-context
/**
* A test function.
*
* @param id
* A test id.
*/
declare function TestFunction(id);
Parsed
{
"type": "Program",
"body": [
{
"type": "TSDeclareFunction",
"id": {
"type": "Identifier",
"name": "TestFunction",
"range": [
81,
93
],
"loc": {
"start": {
"line": 7,
"column": 17
},
"end": {
"line": 7,
"column": 29
}
}
},
"generator": false,
"expression": false,
"async": false,
"params": [
{
"type": "Identifier",
"name": "id",
"range": [
94,
96
],
"loc": {
"start": {
"line": 7,
"column": 30
},
"end": {
"line": 7,
"column": 32
}
}
}
],
"range": [
64,
98
],
"loc": {
"start": {
"line": 7,
"column": 0
},
"end": {
"line": 7,
"column": 34
}
},
"declare": true
}
],
"sourceType": "module",
"range": [
64,
100
],
"loc": {
"start": {
"line": 7,
"column": 0
},
"end": {
"line": 8,
"column": 0
}
}
}
manuth
All 8 comments
So basically only abstract methods and declared methods (TSEmptyBodyFunctionExpression) and function-types (TSFunctionType) are causing trouble as far as I can see.
manuth
on 12 Apr 2020
If you could take a look at #514 , this is mostly ready. But not being too familiar with TS, I'm not sure whether there are other AST configurations such that not all of the ancestors in getDeclaration might be present in some situations.
If TSFunctionType only appears in that context, we can avoid coverage problem by just immediately returning the greatGreatGrandparent rather than doing all of the type checking. But if other ancestor types can exist, we need to add coverage, either showing passing examples where comments on those nodes does not trigger require-param--or, if the user might want @param to be defined in such contexts, then we need to refactor the checks to allow for those other types (and not only support TSFunctionType when in VariableDeclaration > VariableDeclarator > Identifier > TSTypeAnnotation > TSFunctionType as in that PR).
brettz9
on 13 Apr 2020
Awesome - I'll go have a look at it tomorrow!
Thanks for your great effort 😄
manuth
on 13 Apr 2020
Okay so I wasn't that sure what to look for so I just tried to get an overview of all situations where a TSFunctionType might occur.
TSFunctionTypes are used for type-annotations which basically can be put wherever you might want to specify a type.
What comes to my mind are: Return-types, parameter-types, variable-types and signature-types.
I created an AST explorer document for the different occurrences - I hope they are of any help.
manuth
on 14 Apr 2020
That looks helpful, thank you. I might note though--we don't want to avoid jsdoc's for any of these node types; the usefulness of contexts is that the user can choose the context at which their comment rules to apply.
If the user only wants a rule to apply (or not apply) under some conditions, they may have to use a more complicated selector to themselves indicate whether the rule will apply there or not (e.g., FunctionExpression TSFunctionType).
But we do want to help decide where the comment block should be expected to be found relative to the type whenever a comment is being required for a given node type--it may be immediately before the node itself, a parent, a grandparent or great-grandparent depending on the context (e.g., for expressions like let a = function () {}, the comment block would be expected above the statement line (before let a), not immediately before the function expression, function () {}).
brettz9
on 14 Apr 2020
Oh - maybe I've chosen the wrong words - when working with an IDE which uses the TypeScript Server (such as VSCode) I can see that tags like @param don't apply to the FunctionType when it's a parameter-type or a return-type but rather to the function itself.
But of course this might be a very good idea and might help users to be very specific on where to apply jsdoc-rules.
manuth
on 14 Apr 2020
I've added handling for the very helpful test cases you isolated. While there is always the chance that there are more cases to be handled, we can add to it later, and I think this should be a good enough beginning. If #514 looks good to you, I think it should be ready to go ahead and merge.
brettz9
on 19 Apr 2020
:tada: This issue has been resolved in version 23.1.0 :tada:
The release is available on:
Your semantic-release bot :package::rocket:
gajus
on 20 Apr 2020
Related issues
OmgImAlexis
·
5Comments
MaxMilton
·
4Comments
yvele
·
5Comments
AndrewLeedham
·
3Comments
pgoldrbx
·
3Comments
Most helpful comment
I've added handling for the very helpful test cases you isolated. While there is always the chance that there are more cases to be handled, we can add to it later, and I think this should be a good enough beginning. If #514 looks good to you, I think it should be ready to go ahead and merge.