Support a @nonnull/@nonnullable JSDoc assertion comment

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.

[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?

[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!