rustdoc: add nobuild typescript checking to our JS

[notriddle]

By nobuild, I mean that the type annotations are all in comments, not in the "native" typescript syntax. This is a bit uglier, but it lets you rapid-prototype without tsc, works with all the native browser debugging tools, and keeps Node out of Rust's bootstrap chain.

This pull request mostly just adds ts-ignore annotations and type declarations. To actually take good advantage of typescript, we'll want to "burn down" this pile of unsafe code until we eventually have a version with almost none of these.

This PR also adds tsc to the mingw-check Dockerfile, so that it can't fall out of date like the Closure annotations did.

https://rust-lang.zulipchat.com/#narrow/channel/266220-t-rustdoc/topic/typescript

r? @GuillaumeGomez@lolbinarycat

[rustbot]

Some changes occurred in HTML/CSS/JS.

cc @GuillaumeGomez, @jsha

[uellenberg]

It may be better to use @ts-expect-error in place of @ts-ignore. That way, if a change somewhere fixes an error down the line, TypeScript will detect and report it (since expect-error requires that the next line creates an error).

[GuillaumeGomez]

This is impressive. Thanks a lot for this improvement! I particularly appreciate that we don't require TS to build rustdoc, only to check its JS like we do with eslint.

@bors r+

[bors]

📌 Commit d94b64d has been approved by GuillaumeGomez

It is now in the queue for this repository.

[fmease]

FYI: I'm suspecting this caused slight perf regressions. See #136227 (comment). I'll let you be the judge of that :)

[fmease]

the type annotations are all in comments, not in the "native" typescript syntax

Disclaimer: I haven't played around with the newly annotated JS files, so I might be missing some obvious things! Is it actually a hard requirement to use JSDoc's / Closure's type syntax? As far as I understand and have tested, tsc is perfectly fine with using (most) TS type syntax inside JSDoc annotations.

TS's docs call this out (source):

You can use most JSDoc type syntax and any TypeScript syntax, from the most basic like string to the most advanced, like conditional types. [emphasis mine]

Or did you intend to offer people the chance to typecheck the project locally with the Closure compiler instead (which seems to be the only tool other than tsc that can consume and check JSDoc type annotations)?

I guess third party tools (like editors) might suffer from using TS syntax instead. Of course, VS Code's integrated JS/TS language server supports this out of the box.

[fmease]

I was just wondering about that while reviewing #136263 where I saw the JSDoc-style function(): any.

[notriddle]

Or did you intend to offer people the chance to typecheck the project locally with the Closure compiler instead (which seems to be the only tool other than tsc that can consume and check JSDoc type annotations)?

No, you can use all the typescript-specific syntax you want as long as it's in comments (or in metadata files that aren't loaded by the browser). I don't see any point in trying to support multiple type checkers.

[marxin]

@notriddle

Can you please update rustc-dev-guide where a new borked link has been detected?

error: Server returned 404 Not Found for https://github.com/rust-lang/rust/blob/master/src/librustdoc/html/static/js/externs.js
┌─ rustdoc-internals/search.md:482:1
│
482 │ [`externs.js`](https://github.com/rust-lang/rust/blob/master/src/librustdoc/html/static/js/externs.js).
│ ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ Server returned 404 Not Found for https://github.com/rust-lang/rust/blob/master/src/librustdoc/html/static/js/externs.js

[notriddle]

rust-lang/rustc-dev-guide#2248