Add typescript examples

[SkeLLLa]

Partial typescript support was added in #1234, but there are no documentation or examples of usage. Adding some example would be very helpful.

[tusharmath]

Yes Please!

[berstend]

TL;DR 📚

When using the documentation cli with TypeScript:

• Use --shallow command (as module-deps-sortable only understands JS)
• Make sure to add @class & @implements to JSDoc, in case you need it

To get a webserver with your TypeScript documentation:

npx documentation serve --shallow src/index.ts

To add markdown documentation to the API section of your readme: 🎉

npx documentation readme --shallow --readme-file README.md -g -s API ./src/index.ts

---

(original comment)

Uhm. How come this amazing new feature hasn't been documented yet? :)

# using 12.1.4
npx documentation serve src/index.ts

Will choke on typescript syntax despite the PR mentioning:

This is enabled automatically when a file with a .ts or .tsx extension is seen.

I'm gonna dig deeper now how to actually use the new typescript support and will report my findings here (please share if you got it working already).

edit, looks like the cli peripherals expect Javascript:

yarn documentation serve src/index.ts

yarn run v1.19.1
$ /Users/user/dev/os/puppeteer-extra/node_modules/.bin/documentation serve src/index.ts
Error: Parsing file /Users/user/dev/os/puppeteer-extra/packages/puppeteer-extra3/src/index.ts: Unexpected token (14:7)
    at Deps.parseDeps (/Users/user/dev/os/puppeteer-extra/node_modules/module-deps-sortable/index.js:515:28)
    at fromSource (/Users/user/dev/os/puppeteer-extra/node_modules/module-deps-sortable/index.js:450:44)
    at /Users/user/dev/os/puppeteer-extra/node_modules/module-deps-sortable/index.js:444:17
    at ConcatStream.<anonymous> (/Users/user/dev/os/puppeteer-extra/node_modules/module-deps-sortable/node_modules/concat-stream/index.js:36:43)
    at ConcatStream.emit (events.js:215:7)
    at finishMaybe (/Users/user/dev/os/puppeteer-extra/node_modules/module-deps-sortable/node_modules/concat-stream/node_modules/readable-stream/lib/_stream_writable.js:475:14)
    at endWritable (/Users/user/dev/os/puppeteer-extra/node_modules/module-deps-sortable/node_modules/concat-stream/node_modules/readable-stream/lib/_stream_writable.js:485:3)
    at ConcatStream.Writable.end (/Users/user/dev/os/puppeteer-extra/node_modules/module-deps-sortable/node_modules/concat-stream/node_modules/readable-stream/lib/_stream_writable.js:455:41)
    at DuplexWrapper.onend (/Users/user/dev/os/puppeteer-extra/node_modules/readable-stream/lib/_stream_readable.js:577:10)
    at Object.onceWrapper (events.js:299:28)

edit2, turning off dependency resolution using shallow bypasses this and results in output that looks quite ok:

yarn documentation serve --shallow src/index.ts

Unfortunately there's still an issue with the readme command (my main intent) that I'm looking into:

yarn documentation readme --shallow --readme-file README.md -g -s API ./src/index.ts

yarn run v1.19.1
$ /Users/user/dev/os/puppeteer-extra/node_modules/.bin/documentation readme --shallow --readme-file README.md -g -s API ./src/index.ts
TypeError: Cannot read property 'charAt' of undefined
    at Of.inlineCode (/Users/user/dev/os/puppeteer-extra/node_modules/remark-stringify/lib/visitors/inline-code.js:26:13)
    at Of.one [as visit] (/Users/user/dev/os/puppeteer-extra/node_modules/remark-stringify/lib/macro/one.js:20:30)
    at Of.all (/Users/user/dev/os/puppeteer-extra/node_modules/remark-stringify/lib/macro/all.js:14:27)
    at Of.paragraph (/Users/user/dev/os/puppeteer-extra/node_modules/remark-stringify/lib/visitors/paragraph.js:6:15)
    at Of.one [as visit] (/Users/user/dev/os/puppeteer-extra/node_modules/remark-stringify/lib/macro/one.js:20:30)
    at Of.listItem (/Users/user/dev/os/puppeteer-extra/node_modules/remark-stringify/lib/visitors/list-item.js:41:26)
    at Of.unorderedItems [as visitUnorderedItems] (/Users/user/dev/os/puppeteer-extra/node_modules/remark-stringify/lib/macro/unordered-items.js:18:24)
    at Of.list (/Users/user/dev/os/puppeteer-extra/node_modules/remark-stringify/lib/visitors/list.js:12:41)
    at Of.one [as visit] (/Users/user/dev/os/puppeteer-extra/node_modules/remark-stringify/lib/macro/one.js:20:30)
    at Of.block (/Users/user/dev/os/puppeteer-extra/node_modules/remark-stringify/lib/macro/block.js:39:22)
error Command failed with exit code 1.

edit3, I had to modify my class annotation to make it work (I recalled that implements isn't supported yet).

Before (not working):

/**
 * Modular plugin framework to teach `puppeteer` new tricks.
 *
 * This module acts a drop-in replacement for `puppeteer`.
 *
 * Allows PuppeteerExtraPlugin's to register themselves and
 * to extend puppeteer with additional functionality.
 *
 */
export class PuppeteerExtra implements VanillaPuppeteer {

After (working):

/**
 * Modular plugin framework to teach `puppeteer` new tricks.
 *
 * This module acts a drop-in replacement for `puppeteer`.
 *
 * Allows PuppeteerExtraPlugin's to register themselves and
 * to extend puppeteer with additional functionality.
 *
 * @class PuppeteerExtra
 * @implements {VanillaPuppeteer}
 *
 */
export class PuppeteerExtra implements VanillaPuppeteer {

Will work on fine-tuning the output now. :)

Thanks again to everyone working on documentation.js and @devongovett for the TS PR. 💯