Use JSDoc comments for plugin typings

[brodycj]

instead of TypeScript as proposed in #657 (see also #768)

got this idea from: preactjs/preact#1161

It would be ideal to include this in July/August 2018 major release (#773) but I don't expect this to be realistic. Maybe for another new release as tracked in #687.

References:

• Improved JSDoc comments for type correctness. preactjs/preact#1161
• Type Safety for Superfine Source Code Through JSDoc Types. jorgebucaran/superfine#145
• https://medium.com/javascript-scene/the-shocking-secret-about-static-types-514d39bf30a3 (looks like a counterpoint, maybe a nice read)
• https://codeburst.io/five-tips-i-wish-i-knew-when-i-started-with-typescript-c9e8609029db - try some stricter checks?
• https://medium.com/@trukrs/type-safe-javascript-with-jsdoc-7a2a63209b76

[rbiggs]

I totally agree. I used to do TypeScript. Now I just write ES6 with JSDoc comments. Good enough for type safety, intellisense, code completion and refactoring. Let me know with you need help with the JSDoc part. Type casting is probably the most tricky part, and create proper custom types.

[brodycj]

Thanks @rbiggs, may be after the major release. I am actually in a rush against a couple other deadlines right now.

Another challenge is that I currently maintain most of the JavaScript in CoffeeScript, still using coffeescript@1 to compile to JavaScript (without comments) which is also committed. I will probably transition to coffeescript@2 which keeps the comments among other things. I think there are multiple alternative approaches to dealing with CoffeeScript which I would like to investigate when I get some more time, input and feedback would definitely be appreciated.

FYI I have a few additional ideas for preactjs/preact#1161, PR on your fork coming soon.

[brodycj]

prettier/prettier#6286 seems to show how Prettier is adding TypeScript support without even adding a .d.ts file

[rbiggs]

An updated about my own issues using JSDoc for types. For a long time I was noticing that when using JSDoc for type information on a JavaScript module, upon importing VSCode and TypeScript showed no type information for the imported module. Recently I discovered why. I was using a jsconfig.json file that excluded all node modules from projects:

{
  "compilerOptions": {
    "target": "es6",
    "jsx": "react"
  },
  "exclude": [
    "node_modules"
  ]
}

A long time ago the TypeScript team had recommended that. But when you do that with modules using JSDoc for types, those types get ignored by TypeScript. Removing that excludes part allows TypeScript to parse the JSDoc comments of install Node modules and produce first-class Intellisense for VSCode. 💥🎉 So no need for a .d.ts file.

[rbiggs]

Hey bodybits, I noticed that TypeScript was failing to import JSDoc types defined in other files of imported modules. Major bummer for my @composi/core project. I filed a bug with the TypeScript team about it and its now being tracked as a bug in the backlog. Hopefully that means this will get resolved in the next release? Here's the link to the issue: microsoft/TypeScript#33136 (comment)

[brodycj]

Here's the link to the issue: microsoft/TypeScript#33136 (comment)

Thanks @rbiggs, looks like a good find.

[rbiggs]

This is my last nitpick. Modules with types imported from other files that comprise the module should be properly interpreted when you import that module into a new project to use. This works fine inside the module itself. If they can fix this, I feel like I have all my bases covered with JSDoc comments for TypeScript linting.

[brodycj]

Hi @rbiggs, thanks for all of your feedback on this. Considering that I have already started with a redesign, as discussed in #862, I think we should discuss this subject somewhere else.

P.S. I raised composi/core#5 to get this subject better documented in general.