From 963c1c20de118a2e9e60e249e56a5f18c573c8fa Mon Sep 17 00:00:00 2001 From: Christian Murphy Date: Sun, 5 Apr 2020 18:32:47 -0700 Subject: [PATCH 1/2] Use JSDoc to check and generate TypeScript typings --- text/0000-generate-typings-from-jsdoc.md | 74 ++++++++++++++++++++++++ 1 file changed, 74 insertions(+) create mode 100644 text/0000-generate-typings-from-jsdoc.md diff --git a/text/0000-generate-typings-from-jsdoc.md b/text/0000-generate-typings-from-jsdoc.md new file mode 100644 index 0000000..e14f3ec --- /dev/null +++ b/text/0000-generate-typings-from-jsdoc.md @@ -0,0 +1,74 @@ +* Start date: 2020-04-05 +* Scope: collective +* RFC PR: +* Implementation issue(s): + +# Summary + +Generate TypeScript typings from JSDoc. + +## Basic example + +An example of this can be seen at . + +## Motivation + +Currently typings are hand generated based off reviewing the API documentation. +As changes to the API are made, the typings need to be updated, but there is currently no mechanism in place that checks that the two still match. +This can cause drift between what the API actually does and what the typings say the API does. + +The goal is to close the gap between the source, the API, and the typings keeping them in sync. + +## Detailed design + +TypeScript supports checking types and generating typings files based off [JSDoc comments](https://jsdoc.app). + +Using documentation comments with TypeScript has several advantages: +1. It allows TypeScript to validate the typings match the source +2. It keeps comments in the code in sync with comments in the typings (used by IDEs that support TypeScript) +3. It keeps the source in JavaScript + 1. Allowing the repository to be added as a dependency directly from git + 2. Avoiding a rewrite in TypeScript ([Which has growing and significant adoption, but as of 2019, 42.5% of JavaScript developers are unfamiliar with it or don't use it](https://2019.stateofjs.com/javascript-flavors/typescript)) + +## Drawbacks + +There are several drawbacks to this approach: +1. TypeScript driven by JSDocs is a newer feature in TypeScript, not all TypeScript developers are familiar with the feature or it's syntax, there may be an additional learning curve. +2. Not all JavaScript developers are familiar with JSDoc, or with type annotations, there may be an additional learning curve. +3. It would require some refactoring, TypeScript discourages reassignment to a variable with different types (For example `foo` being a `number` the later a `string`). + +## Alternatives + +1. Rewrite the code in TypeScript +2. Continue to maintain the types separate, but add a reminder in the PR template, and encourage maintainers to check types before merging changes + +## Adoption strategy + +> If we implement this proposal, how will existing unified developers adopt it? + +Many unified packages have typings, for these packages, the typings would get more accurate. +For packages that previously did not have typings, typings would be natively provided. + +> Is this a breaking change? + +For packages which did not previously have typings, yes. +For packages with existing typings, this could be considered minor or even patch. + +> Can we write a codemod? + +Maybe, () might be able to be used to extract full types from the source using the test suite as a runner. +Since the conversion from type profile to TypeScript doesn't exist today, and because some types may not be able to be directly converted (see drawback 3). + +It may be easier to do some manual refactoring. + +> Should we coordinate with other projects or libraries? + +Potentially with: +* +* who have also taken the [TypeScript with JSDoc approach](https://dev.to/open-wc/generating-typescript-definition-files-from-javascript-5bp2), and also are using [Remark](https://github.com/open-wc/open-wc/tree/master/packages/mdjs) +* another project with leverages both TypeScript and Remark, and has members who are also a part of the collective. +* an MDX and collective project using Remark with TypeScript. + +## Unresolved questions + +None From fd4c73772a3728fa68b579e027981ee8e25286b9 Mon Sep 17 00:00:00 2001 From: Christian Murphy Date: Mon, 6 Apr 2020 12:29:38 -0700 Subject: [PATCH 2/2] note increased file length as downside Co-authored-by: Titus Wormer --- text/0000-generate-typings-from-jsdoc.md | 1 + 1 file changed, 1 insertion(+) diff --git a/text/0000-generate-typings-from-jsdoc.md b/text/0000-generate-typings-from-jsdoc.md index e14f3ec..cde5cf7 100644 --- a/text/0000-generate-typings-from-jsdoc.md +++ b/text/0000-generate-typings-from-jsdoc.md @@ -36,6 +36,7 @@ There are several drawbacks to this approach: 1. TypeScript driven by JSDocs is a newer feature in TypeScript, not all TypeScript developers are familiar with the feature or it's syntax, there may be an additional learning curve. 2. Not all JavaScript developers are familiar with JSDoc, or with type annotations, there may be an additional learning curve. 3. It would require some refactoring, TypeScript discourages reassignment to a variable with different types (For example `foo` being a `number` the later a `string`). +4. Increased source code length, including detailed comments inline can increase number of lines in a file significantly. ## Alternatives