Closed homer0 closed 4 years ago
yamalight
commented
4 years ago You've basically read my mind here, haha. I've been thinking about doing a stream comparing typescript and jsdoc. Build a small simple lib using ts and plain js, then import it and see what provides better experince 🤔
yamalight
commented
4 years ago And done! Code: https://github.com/BuildingXwithJS/jsdoc-vs-typescript Stream: https://youtu.be/pWIFRloBT68
homer0
commented
4 years ago @yamalight Hey Tim! I couldn't make it to the livestream 😭 (timezone issues), but I just finished watching the VOD and it was great :D.
Last week, when you rescheduled the streaming, I actually started checking JSDoc "in depth"... I spent the whole weekend fixing type definitions on a project :P.
Now, the reason I'm commenting on the closed issue, besides thanking you for the streaming, it's because there were a few things you didn't mention and that may be useful for you to know:
The return of JSDoc
JSDoc it's indeed coming back now; even if it exists since '99, they didn't update it on time for ES6, so you couldn't document classes, arrow functions, default parameters, etc.; that made a lot of people leave it (that's how I ended up using ESDoc).
I believe they started supporting it mid-2016 (with issues).
Part of the reason its popularity it's increasing again is VSCode (and I believe WebStorm also picks the types from the comments now).
TS-Server !== JSDoc
Most of the syntax you used for the JSDoc comments was actually TypeScript; as you mentioned, VSCode uses the TS-Server under the hood to pick the JSDoc comments, but the TS-Server doesn't parse the comments with actual JSDoc (the tool), it uses it's own parser
And since the TS-Server parser is not JSDoc, it allows you to be "hacky", like using @type without brackets (you did this :P), or import types using @typedef {import('...'/typedef).Something} Something... but at the same time, if something goes wrong, you end up with any without no idea of what happened. It took me half an hour to figure out that you can't use @description on @typedef "on VSCode".
And I won't even touch (Object vs object) + JSDoc :P.
Also, this means that the intellisense you get from VSCode may not be the same you would get on another IDE/Editor.
Right now I'm working on a setup with eslint-plugin-jsdoc, to validate the syntax, a custom plugin to be able to use the "TypeScript hacks" when I write the code, and the JSDoc tool to generate the documentation site... it's been painful, but I just finished updating the site template (one of the other reasons JSDoc wasn't very popular... there are like just 4 (proper) themes for the generator).
Ok, I hope those comments are helpful to you, thanks again for accepting the proposal, I really enjoyed the streaming :D!!
Regards!
(Once I merge all the things, I'll share you the repository so you can check the setup :))
yamalight
commented
4 years ago @homer0 whoa! that's quite a lot of cool info, thanks for sharing that! ❤️
Hi!
I've been watching your streams for long time now, and I share most of your opinions about TypeScript; when you decided to migrate ExoFrame I though "ok, if Tim is giving it a chance, I may have to rethink it", but after watching you struggle for 4hs, I'm even more convinced that I don't need it on the majority of my uses cases.
Now, as you mentioned a few times, you can achieve very useful results with JSDoc, but the current scene of JSDoc is kind of complicated:
I've used ESDoc on the past, but it's abandoned now (there are a few of old forks), and its dependencies are all deprecated, vulnerables, and in some cases, cause conflicts.
Finally, I was wondering if you could show us how would you setup JSDoc (or an alternative) for properly documenting a vanilla project (*) and then generate a documentation site based on it.
I hope you consider this proposal. Regards.