Postcss: Use TypeDoc instead of JSDoc

[jedmao]

In response to @ai's comment here, I suggest we use JSDoc annotations to provide type information in JavaScript files w/o a TypeScript build step.

Related

• https://github.com/postcss/postcss/issues/452

[ai]

Good idea

[jedmao]

@aoberoi you might like this idea too.

[aoberoi]

@jedmao interesting idea indeed! Could this work possibly help in the problem of having to synchronize the type definitions outside the source code? Specifically, do you know if there’s a way to run tsc to output declaration files (.d.ts) from comments in the proposed style?

[aoberoi]

It seems the types that can be specified using JSDoc comments are still less expressive than TypeScript (most of the advanced types are missing, such as generics, mapped types, intersections, etc). However, if we’re not going to author the source code in TypeScript, this would still be a good compromise towards making PostCSS more usable for TypeScript users.

I recently heard this advice: “if you aren’t going to write the code in TS, then no types is better than wrong types”. This leads me to believe that if we go down this route, we should remove the .d.ts file from this repo so that there’s only one source of truth (the JSDoc comments). Something to consider, since that’s quite a large trade off.

IMHO if we’re going to have an unsynchronized declaration file, it shouldn’t be in this repo, but rather in DefinatelyTyped, so that it’s opt-in and wrong declarations don’t get in the way of productivity.

[jedmao]

1. Yes, this would kind of solve the whack-a-mole situation we're in.
2. From what I understand, you would run tsc --noEmit on the js code to see if it passes the TS compiler.
3. I don't know if you can generate the .d.ts file from it, but I don't think you need to either, because it would just get the types directly from the JS source.
4. I'm not sure how less expressive the types are in JSDoc comments. Are you 100% sure they don't accept generics? Because I love generics! I understand the need for a compromise though.
5. I'm also wondering if we might want to add // @ts-check at the top of each file for additional type safety checks or if that's even needed.
6. Moving the .d.ts file to DefinitelyTyped might confuse some peeps though. Having two options is always confusing and I'm not even sure which one would override the other or if it would do some kind of declaration merging? Never done this before.

[jedmao]

This issue, should it be implemented, would also allow us to use tsickle to further optimize the bundle size.

As a side note, here is the history of PostCSS with respect to compilation steps.

History of PostCSS

1. Sep 7, 2013 - Initial commit in CoffeeScript.
2. July 23, 2014 - Converted into ES5 via Traceur.
3. July 27, 2014 - via es6-transpiler.
4. November 12, 2014 - via 6to5 (now Babel).
5. August 19, 2015 - Babel.
6. January 17, 2019 (today) - Still using Babel.

_Credit goes to @DrewML for pretty much everything above._

[DrewML]

It seems the types that can be specified using JSDoc comments are still less expressive than TypeScript (most of the advanced types are missing, such as generics, mapped types, intersections, etc)

This is not accurate. I've yet to find a type I could not model with JSDoc. Per the constructs you mentioned:

Generics + Mapped Types

/**
 * @typedef {{ readonly [P in keyof T]: T[P] }} ReadonlyExample
 * @template T
 */

VSCode showing TypeScript Language Service type

Union Types

/**
 * @typedef {Object} Foo
 * @property {string} foo
 */

/**
 * @typedef {Object} Bar
 * @property {string} bar
 */

/**
* @typedef {Foo & Bar} FooBar
*/

/** @type {FooBar} */
const FooBarValue = {
    foo: 'foo',
    bar: 'bar',
    bizz: 'test' // bizz properly gets flagged as not being a member of Foo & Bar
};

VSCode showing TypeScript Language Service type

[ai]

I think I will move from JSDoc to TypeDoc in 8.0

[ai]

Done eeee4ab