search

vuejs / vue

This is the repo for Vue 2. For Vue 3, go to https://github.com/vuejs/core
http://v2.vuejs.org
MIT License
207.95k stars 33.68k forks source link

Add JSDoc to types #10320

Open Shinigami92 opened 5 years ago

Shinigami92 commented 5 years ago

What problem does this feature solve?

This will improve the developer experience when using Vue in editors such as VSCode.

Currently, the developer must look up the default value in the documentation. And even there it is not clear, without trying it.

What does the proposed API look like?

One example:

https://github.com/vuejs/vue/blob/b7c2d9366cf731a1551286b8ac712e6e0905070e/types/options.d.ts#L155

This line could get a JSDoc like:

Indicates whether the property must be set or is optional. Default is `false`.

Example Result

Bildschirmfoto 2019-07-29 um 11 03 36

naisuuuu commented 5 years ago

Wanted to implement this, realized that while the guide section of the documentation does not provide clear information about default values, the api section does.

Having a second source of truth to the official documentation is likely to cause more confusion than be convenient down the line. (outdated JSDoc comments are easily overlooked)

Opinions?

kinow commented 5 years ago

@ww7w could the JSDoc be used to generate the documentation?

naisuuuu commented 5 years ago

@kinow its definitely possible, but having to write the API documentation inside of type definition files introduces its own separation of concerns issues.

Also, JSDoc doesn't have one unified spec, which makes it hardly suitable for anything more than short comments like the one in the example.