Open fmpanelli opened 4 years ago
A possible approach would be to copy the comments from lib/taiko.js
to types/taiko/index.d.ts
That would create a huge duplication of information between the two files and make them practically un-mantainable.
An alternative which I would like to explore is to automatically generate the index.d.ts
from lib/taiko.js
's JSDoc, using the facilities provided by the TypeScript compiler since ver 3.7.
Although this is possible in theory, there are some points to be clarified:
is it possible to write the JSDoc comments that is compatible both with the TypeScript compiler and with the documentation generator used by taiko?
adding TypeScript to the project has consequences e.g. on eslint
or similar?
Any other idea to approach the problem?
Thanks for picking this up and for all those PR's to add TypeScript support such great effort. Since I worked on setting up the documentation site I can add some context about document generation.
Taiko uses inline documentation to make documentation within the IDE's more accessible, this is important. The documentation at https://docs.taiko.dev/api/reference is parsed from JSDoc comment which are exported to json using https://documentation.js.org.
is it possible to write the JSDoc comments that is compatible both with the TypeScript compiler and with the documentation generator used by taiko?
I think it can be compatible since Taiko uses a custom parser that reads from an exported api.json file. It ignores other tags. So you could add Typescript specific tag and generate the *.d.ts
file. It is also easy to tweak the parser to read TypeScript specific info in the generated documentation. From the TypeScript's JSDoc reference it looks like @example
is the only extra tag that Taiko is using.
adding TypeScript to the project has consequences e.g. on eslint or similar?
If you meant eslint in the documentation, I don't think so.
@zabil Thanks for the advice. And thanks to the whole team for the open and welcoming attitude in this community.
I am experimenting on my machine to understand the process of the automatic generation of declaration files and it looks promising (and I hope I will be able to reuse all the type tests built with the previous PR's).
For sure some changes to the JSDodc comments are required generate the correct types.
E.g. for the function into
the type manually declared in index.d.ts
is now:
// https://docs.taiko.dev/api/into
export function into<T extends string | Selector>(value: T): T;
In order to obtain the same result I had to change the JSDoc like this:
This is the one of the easiest examples. Doing something like that for all the type declarations is gonna be challenging...
I used the sample above to generate the api.json
using TypeScript style JSDoc
"tags": [
{
"title": "example",
"description": "await write(\"user\", into(textBox('Username:')))",
"lineNumber": 3
},
{
"title": "template",
"description": "{string|selector}",
"lineNumber": 6
},
{
"title": "param",
"description": "value to be returned",
"lineNumber": 7,
"type": {
"type": "NameExpression",
"name": "T"
},
"name": "null-null"
},
{
"title": "return",
"description": "the value provided in input",
"lineNumber": 8,
"type": {
"type": "NameExpression",
"name": "T"
}
}
]
This is tough to parse as the info is not inside the scope of the parameters. However if I modify it to @type
the documentation parser generates something that can easily be parsed
/**
* This function is used to improve the readability. It simply returns the parameter passed into it.
*
* @example
* await write("user", into(textBox('Username:')))
*
* @type {string|selector}
* @return {string|selector}
*/
module.exports.into = (value) => value;
Generates
"tags": [
{
"title": "example",
"description": "await write(\"user\", into(textBox('Username:')))",
"lineNumber": 3
},
{
"title": "type",
"description": null,
"lineNumber": 6,
"type": {
"type": "UnionType",
"elements": [
{
"type": "NameExpression",
"name": "string"
},
{
"type": "NameExpression",
"name": "selector"
}
]
}
},
This should be easy to parse by the document generator. Do we really need to use @template? Shouldn't @param
or @type
work for generating the .d.ts
file?
Mmmmhh... I start to get the picture...
Let me think about it for a few days... Maybe I can come up with actual code we can discuss.
I made some analysis and experimentation.
taiko.js
and in the classes under lib/
as they are today don't enable the automatically generated types to reach the same quality of the manual declarations and they will need improvementsdocs.taiko.dev
website documentation is currently able to represent correctly the basic types and it can be gradually extended to deal with more complex types (e.g. it already supports methods returning instances of lib/elementWrapper/*.js
classes)Promise
or a *Wrapper
object, but not a type like string
b. function params with types like {string|number}
do not get a type displayed on the page
c. function params which are instances of a class do not get a type displayed on the page
d. definition of types with @typedef
is ignored by the documentation system, we may want to treat it with a dedicated typedef.njk
similar to class.njk
I guess all of the previous points (except maybe no. 5) were already inside the suggestions of @zabil, but now I fully understand 😀
If you agree I would propose to proceed as follows:
@zabil, if you are ok with that I can start working on this plan
👍 This sounds good.
Expected behavior
Since Taiko has support for Tyescript types, when editing in VS Code you will see IntelliSense suggestions for auto-completion including types for functions and arguments. I would expect also the JSDoc comments that are found in
lib\taiko.js
to be shown.E.g. for
openBrowser
I would expect a formatted version of the following to be shown when hovering the function name in VS Code:Actual behavior
The documentation is not shown, but only the types (actually it show "Browser Actions" which is wrong):
I guess this is because the comments are not present in
types/taiko/index.d.ts
but only inlib/taiko.js
.Steps to reproduce
npm i taiko
example.ts
belowVersions