Typescript: Support a @nonnull/@nonnullable JSDoc assertion comment

[DanielRosenwasser]

This could be used in place of the non-null assertion operator, and solve #23403.

while (queue.length) {
    (/** @nonnull */ queue.pop())();
}

Related is #23217, which tracks definite assignment assertions.

[RyanCavanaugh]

@sandersn please add /** @nonnull */expr as JS sugar for (expr as NonNullable<typeof expr>) 🍻

[weswigham]

@RyanCavanaugh Or more appropriately as sugar for expr!, which is _almost_ just sugar for (expr as NonNullable<typeof expr>), but also has fallback behavior if NonNullable doesn't exist.

[RyanCavanaugh]

That's the easier and more correct way to write it, yes 😝

[sandersn]

I'm not super excited about this suggestion because it doesn't improve the clunkiness of the existing solution. We are comparing

/** @type {() => void} */(expr)
/** @nonnull */(expr)

The two obstacles come from the cast syntax, not the contents of the comment: you need (1) a C-style comment that (2) is followed by a parenthesised expression. Note that the original example is wrong. You'd need /** @nonnull */(queue.pop())(). You're in for a bunch of punctuation and some confusing parentheses.

Given those two things, the difference between @nonnull and @type {*} is pretty small (1 character, to wit). Even @type {() => void} isn't that much of an improvement.

If sugar were free, I'd be happier about this proposal.

Edit: Updated with @weswigham's even smaller syntax.

[weswigham]

@sandersn you can shave two characters - @type {*}

[weswigham]

I think there's an important difference between a cast and a nonnull assertion, from the typechecking perspective, however - a nonnull doesn't destroy type information (ie, for quick info or inference), while an any cast does.

[brendankenny]

any sort of DOM stuff can be pretty annoying without a simple nonnull assertion operator, especially as the DOM d.ts files get tightened from webidl generation (I mean, technically document.documentElement can be null, but in practice... :)

This is wandering way out of the usual jsdoc area, and it may be a terrible idea, but what about expr/**!*/ as sugar for expr!

[TheLarkInn]

Bump for awesomness!

[trusktr]

what about expr/*!/ as sugar for expr!

I like this.

In cases like this where comments do not specifically serve a documentation-for-humans purpose, but a documentation-for-ts-compiler purpose, I believe the rules should not specifically follow JSDoc rules.

Here's why:

JSDoc comments were designed to serve a documentation-for-humans purpose (for example the prose in a comment may end up on a documentation website or something similar).

If all type-oriented comments are limited to following JSDoc format, this interferes with existing JSDoc tooling:

1. Some JSDoc tools do not take into account any code, and read nothing more than comments in a file.
   
   
   
   • Encountering an island /** @nonnull */ in the extracted comments would have no semantic meaning, for example.
   
   
2. For JSDoc tools that _do_ inspect code in order to infer more information from the code, having a /** @nonnull */ floating in front of an expression still doesn't make semantic sense.
   
   
   
   • A non-TypeScript doc tool would have no idea what documentation to generate from this if it didn't crash, and even in a TSDoc environment it isn't worth documentingsuch things; only TSDoc will explicitly know not to document it.
   
   

I've seen projects purposefully use JSDoc instead of TSDoc tooling for various reasons, a primary reason being that the developer wishes to be in precise control of the documentation output so that what one writes is exactly what one gets. This is in contrast to TSDoc which often documents too much that isn't semantically important and gives little (or difficult) control over the output.

We can get _all_ the type information we need from an IDE with good intellisense, while otherwise leaving semantic documentation-for-humans to JSDoc comments (as well as JSDoc tools if you prefer, like I do).

Yes, maybe we can tell JSDoc tools to ignore the strange parts they don't understand (like random /** @nonull */ comments floating around, but that complicates the tools in unwated ways just to satisfy TypeScript (I've written my own JSDoc parser and documentation generator, so this is my first-hand sentiment).

I believe we should keep JSDoc comments pure to their purpose, as first-class citizens in documentation for humans, and leave anything else (documentation for the TypeScript compiler) in a different syntax, if possible.

Wdyt?