Simpler `examples` workflow using plain JS files and JSDoc comments

[JKRhb]

At the moment, the current workflow for the examples prescribes using TypeScript for the source files whose resulting compiled JS files are then copied over to the top-level examples directory, including a manual removal of some added lines.

To keep both the benefits of TypeScript and the possibility to use plain JavaScript, I think a much simpler and more ergonomic approach would be to directly use JavaScript files and enable type checking via JS Doc comments. By using a // @ts-check comment at the top of the file, we would still get the benefit of type checks without the compilation and copying step. This would also give us more control over the resulting JS-based examples.

This suggestion corresponds partly with the discussion started by the recent shift of the Svelte library from TypeScript to plain JavaScript with JSDoc comments (see, e.g., here).

[JKRhb]

Just noticed that this would be a potential alternative to #185.

[danielpeintner]

I like the idea! I did not try it myself but just by reading the Svelte article you shared this seems to be right (or at least a good) approach for a library such as node-wot.

The missing part/questions I see/have are

• we might need to go over the code-base and check whether we have proper JSDoc comments were needed
• Question: Let's assume we have a breaking change. Do we get a build issue (notification?) for the JS examples once we enable proper type checking for JS? I assume so.

Moreover, this might also affect how we deal with test-things in the future (ping @egekorkan).
Additionally we could (should?) remove the package "examples" and just keep the plain JS examples.

@JKRhb thank you for kicking off this discussion 👍