[HN Gopher] Jsdoc Cheatsheet
___________________________________________________________________
Jsdoc Cheatsheet
Author : susam
Score : 24 points
Date : 2023-02-05 11:45 UTC (11 hours ago)
(HTM) web link (devhints.io)
(TXT) w3m dump (devhints.io)
| Alifatisk wrote:
| Totally forgot about devhints!
| clarkdale wrote:
| It would be interesting if this documentation was written
| directly into the code itself. For instance the default value is
| already right there. TypeScript adds the type information. If
| there was a way to add comments on each parameter name, so that
| the compiler didn't remove it, that would be neat. I mean inside
| the function itself.
| augusto-moura wrote:
| Flow Type had a way of embedding type code in JS block comments
| [1]. There is an open issue for Typescript, but it looks it
| didn't went too far [2]
|
| [1]: https://flow.org/en/docs/types/comments/
|
| [2]: https://github.com/microsoft/TypeScript/issues/9694
| orta wrote:
| Here's hoping https://tc39.es/proposal-type-annotations/ solves
| this
| billti wrote:
| If you're using VS Code as your editor, its JavaScript editing is
| powered by the TypeScript engine's support for JS. The JSDoc
| support there is pretty good, as are the docs for the syntax
| supported.
|
| https://www.typescriptlang.org/docs/handbook/jsdoc-supported...
| jjice wrote:
| I wasn't able to sell TypeScript for a new project to by boss,
| but I noticed that JSDocs gave me a lot of power in the editor
| at least, and everyone loves a good doc comment. I'm basically
| getting to live the bastardized TS lifestyle, and honestly, I'm
| very okay with it.
| 29athrowaway wrote:
| My reply to people not wanting to use TypeScript is "Show me
| your unit tests". They are often full of type validations.
|
| So they've already paid the cost of a strongly typed language
| without any of the benefits.
|
| And when type validations are missing their issue tracker is
| full of type mismatch related bugs.
|
| The lazy works twice. Just use types, the computer is better
| at comparing large amounts of strings than humans.
| 01ce8c91872dd6d wrote:
| and my reply to you would be showing you virtually any TS
| codebase I ever saw.
|
| strict typing is great, but the rest of TS features are
| just trying to put Java into Javascript, empowering people
| to turn 100 LOC worth of functionality into 1000 LOC of
| cruft
| johnfn wrote:
| > strict typing is great, but the rest of TS features are
| just trying to put Java into Javascript
|
| There are no other features of TS that aren't static
| typing. It is only static typing. (OK, I suppose you
| could make an argument for enums, but it's still 99%.)
| llamaLord wrote:
| Are you serious right now???
|
| Like... Half the original point of TS was to add features
| to JS that weren't there originally.
|
| Granted, as the base language evolved the gap has become
| smaller, but it's still there.
|
| Interfaces being one such example.
|
| There's also things you can do in JS that TS will bitch
| about. For example, try using object destructuring in a
| class constructor to create optional named parameters for
| a class.
|
| Works perfectly in Vanilla JS, but TS will throw a hissy-
| fit.
| nosianu wrote:
| > Are you serious right now???
|
| He (or she) is totally serious and I agree.
|
| Here is what I wrote here in some discussion a few days
| ago: https://news.ycombinator.com/item?id=34454774
|
| -----
|
| TypeScript isn't another language though. It is the
| latest official ECMAScript plus type annotations. Only
| some very, very few, rare, old stuff like enums really is
| different code. 99% of TypeScript is just "remove the
| types to get ECMAScript".
|
| That TypeScript, the tool,also adds a transpiler is a
| distraction that made a lot of people believe TS is a
| different language. But the TS folks have always taken
| great pain to only ever support features that are or are
| about to be in the ECMAScript standard, and not to
| deviate from it. That they did initially with some
| namespace stuff and enums was before ES2015, when JS was
| lacking some things many people thought were essential.
| Even then they only added less than a handful of
| "TypeScript-code".
|
| When you look at the Babel "transpiler" for Typescript,
| before they added a bit more for class stuff, it pretty
| much showed that "transpilation" of TS to JS - as long as
| you targeted a recent ES version - was achieved by doing
| nothing more than to remove all those type annotations.
|
| I'm still mad at the TS guiys for muddying the waters so
| much by confusing soooo many people by bundling type
| checking and transpilation in one tool. This could have
| been much more clear. I too stuck to using Flow for quite
| some time until I realized TypeScript really is
| Javascript, while Flow communicated in its architecture
| and usage already that it just "added types" (literally).
|
| ------
|
| Actually changing the nature of Javascript, and quite
| radically too, were those who wrote the newer spec
| themselves - introducing more and more "class" things.
|
| > _Interfaces being one such example._
|
| They are not part of the JS code produced, they are
| simply type annotations. They don't change the actual JS
| code at all.
|
| Being fine with JSDoc but not with TS types is strange to
| me, there is no difference as far as the JS code outcome
| is concerned unless you - needlessly! - use the very few,
| mostly legacy (made obsolete by ES2015+), things in TS
| that actually end up as JS.
|
| Just treat the TS types exactly the same as the JSDoc:
| It's just comments, it's not part of the code! Get it
| removed by Babel or tsc just like you could remove (as
| packers will do) the JSDoc comments for a production
| build.
|
| I once started with Flow (the other JS type checker),
| experimented with JSDoc+Webstorm as praised here, and
| very quickly found an actual type checker and full type
| annotations are far superior.
|
| Maintenance and team work, especially when people change
| what projects they are working on, and even more when you
| have (your own) libraries that other teams use to build
| something atop of, then string types are a godsend IMO.
| And why would I go for the far inferior JSDoc "solution"?
|
| I too am VERY keen on using ECMAScript. If TypeScript
| really messed with the underlying code I would not have
| chosen it. I simply avoid enums and the other stuff is
| not even on the radar any more, nobody needs to use the
| namespacing hacks any more that TS once introduced
| because prior to ES2015 JS was severely lacking.
| MrJohz wrote:
| The only new runtime feature that Typescript brings to
| Javascript is enums.* Everything else is just types.
| Interfaces, for example, are just a way of defining a
| shape that data will fit to. They are (almost) equivalent
| to the `type MyType = { key1: string /* etc */ }`
| construct, and behave more like an ML record type than a
| Java interface.
|
| Also, I don't know what exactly you're describing, but
| objects as optional named parameters are a common
| technique in Javascript and therefore very well sorted in
| Typescript. I'm on my phone so this might not work
| brilliantly, but something like this:
| // This could also be an interface... ;) type
| Params = { // These keys are optional
| // (Note the question mark) height?: number |
| string width?: number | string }
| class Rectangle { constructor({height,
| width}: Params = {}) {
| console.log(height, width); } }
|
| I've not checked that, but it should type check fine. We
| need to tell Typescript that the param keys can be
| optional, I used the question mark here, but if you've
| already got a type, you can use the Partial<T> type to
| cover it to having all optional keys. We also need to see
| a default value if the object isn't passed, but that's
| true in Javascript as well (otherwise we'd get a runtime
| exception that you can't destructure undefined).
|
| I can definitely empathise with the idea that some
| Typescript developers just use it as an opportunity to
| write Javascript-flavoured Java, but this is mostly a
| stylistic choice (and completely possible in raw
| Javascript too). But Typescript is very explicitly
| designed you match the usage patterns of Javascript
| directly - i.e. if your Javascript code runs (and makes
| sense), you should be able to write an identical version
| in Typescript and have it be accepted by the type
| checker. Obviously that's never going to be entirely the
| case, but I really find I have many issues porting
| idiomatic Javascript too Typescript - and where I do,
| it's usually because the Javascript was wrong in the
| first place.
|
| * That's not actually entirely true, I forgot about field
| declarations in constructors, but I don't think I've ever
| seen that used in the wild outside of very old Angular
| codebases.
| wffurr wrote:
| >> Try using object destructuring in a class constructor
| to create optional named parameters for a class. Works
| perfectly in Vanilla JS, but TS will throw a hissy-fit.
|
| What?
|
| You mean like this? class Foo {
| constructor({opt1, opt2, opt3}: {opt1: string, opt2?:
| number, opt3?: Object}) { }
| }
|
| https://www.typescriptlang.org/play?#code/MYGwhgzhAEBiD29
| oG8...
| wffurr wrote:
| >> the rest of TS features are just trying to put Java
| into Javascript, empowering people to turn 100 LOC worth
| of functionality into 1000 LOC of cruft
|
| Not sure what features those are, but TypeScript still
| has first-class functions, higher-order functions, and
| algebraic data types. Those are all excellent tools for
| not writing Java. If people are writing Java code in
| TypeScript, they're missing out on all the features and
| power available to them that aren't in Java.
| 29athrowaway wrote:
| Have fun doing extra work:
|
| - writing unit tests that will likely be not exhaustive
|
| - refactoring your unit tests constantly each time you
| change something
|
| - do all that without the assistance of a compiler
| telling you what broke
|
| - having to read code to infer types by hand
|
| All all of that for what? so that your code still breaks.
|
| Comparing strings by hand is certainly the best use of
| human time. If we only had machines capable of doing
| that.
|
| > My velocity is so high! Look at all those "type
| mismatch" Jira tickets I've closed in the last month! I
| am a 10xer. I've multiplied my work 10x!
|
| - Average TypeScript hater testimonial
| llamaLord wrote:
| I hate TS, I use proper OOP style JS with JSDOC and
| Webstorm type-hints.
|
| Never have any of the issues you mention and even better,
| never have to deal with the fucking Typescript
| compiler...
| ihateolives wrote:
| > trying to put Java into Javascript,
|
| Our current project has Java in the backend written in
| Java and Java in the frontend written in Typescript. So
| many layers of abstractions for submitting forms.
| llamaLord wrote:
| Webstorm + JSDOC is a superior alternative (IMO) to Typescript.
|
| You get 99% of the benefit, with no bitchy Typescript compiler
| to deal with.
| emj wrote:
| While I love a standard for API documentation, these kinds of
| documentation is seldom of use for me when I read code, it is
| usually the same boiler plate you see in this cheat sheet: "X a
| number". Git commits are ment to be similarly short there it is
| the what and why, in code I often feel you need the why and how,
| rather than what for function arguments.
| alexose wrote:
| I feel the same way. Maybe it's because I came to programming
| in a roundabout way (i.e., no formal training), but I just see
| JSDoc-style annotations as wasted characters.
|
| Again, maybe just me. But, my brain doesn't parse them unless
| the code is already extremely well structured. In which case,
| why include annotations at all? Or in other words, isn't it
| always better just to improve the readability of the function
| itself?
| gl-prod wrote:
| They aren't really designed for your brain to parse them;
| they help your IDE understand quickly what's happening.
| kjksf wrote:
| JSDoc provides type annotations in comments.
|
| They are (mostly) not for you.
|
| They are for the tooling, including your editor, to detect that
| your declared foo(bar: string) but you're calling it as foo(5).
|
| The value of JSDoc is the same as value of TypeScript: add
| static types to your code to detect bugs.
|
| And yes, it works in practice.
|
| I started using JSDoc quite recently.
|
| I don't enjoy adding those type annotation comments but
| undeniably they (and VS Code tooling, jsconfig.json) detect
| errors that, if not fixed, would end up blowing up at runtime
| and causing me to spend more time fixing them.
| 29athrowaway wrote:
| If I could downvote this a million times, one click at a time
| until my mouse button stops working, I would.
|
| Documentation tags have a machine readable structure.
|
| That structure can be parsed and used for documents, editor
| hints, diagrams, and even type check validations.
|
| Instead of having to traverse the entire callgraph of a
| function to have an idea of what guarantees it provides, you
| simply read the documentation tag.
|
| This is O(1) instead of O(V+E) where V are the functions and E
| are how you call them.
| allendoerfer wrote:
| > That structure can be parsed and used for documents, editor
| hints, diagrams, and even type check validations.
|
| > Instead of having to traverse the entire callgraph of a
| function to have an idea of what guarantees it provides, you
| simply read the documentation tag.
|
| > This is O(1) instead of O(V+E) where V are the functions
| and E are how you call them.
|
| Unless of course it is wrong, because it is just a convention
| for a comment and not actually an enforced type.
___________________________________________________________________
(page generated 2023-02-05 23:01 UTC)