developit / preact / 2317

100%

push

travis-ci

Improve JSDoc comments (#1115)

Update Preact's JSDoc comments to better reflect the current code and improve editor experience (if using editor with TypeScript support/extension). I make use of `@typedef`s to define a couple of key complex types used by Preact. Each complex type is described below.

## Complex Types

**Options**: Documents all the public options a consumer of Preact can define

**VNode**: Documents the properties of a Preact Virtual DOM Node

**PreactElement**: Documents all of the properties Preact adds to the DOM elements it creates

## What about Component?

I haven't exhaustively documented Component in this PR because that is a much more complex type to document in JSDoc and I'm considering doing it in its own PR to discuss different ways of how to accomplish it. I've started experimenting with how to do this in my [update-jsdoc-component-doc branch](https://github.com/andrewiggins/preact/blob/update-jsdoc-component-doc/src/component.js) if you are curious.

## Other Notes

These JSDoc comments rely on a new feature in Typescript 2.9, "[allow `import(...)-ing` types at any location](https://github.com/Microsoft/TypeScript/wiki/What%27s-new-in-TypeScript#allow-import-ing-types-at-any-location)". I use this feature to import `@typedef`s across files. The next version of VSCode should include TS 2.9 by default so these comments will work by default in that version. If you'd like to check out the TS 2.9 experience now, check out this branch and set the VSCode workspace setting `typescript.tsdk` to `node_modules\\typescript\\lib`.

This PR does not eliminate all errors that appear in the editor. In order to do that Preact would likely need to embrace full TypeScript or Flow syntaxes to utilize the entirety of features those languages offer. It might be possible to remove all errors using only JSDoc syntax however I'd like to explore that possibility in a separate PR as it might require an additional significant amou... (continued)

467 of 497 branches covered (93.96%)

1 of 1 new or added line in 1 file covered. (100.0%)

15 of 15 relevant lines covered (100.0%)

524190.33 hits per line