Decide how CKEditor 5-provided types should be referenced

I wonder if this blocks #3248430: Improve Drupal.ckeditor5 documentation? 🤔

So I have a way to make documentation show up in PhpStorm but it's not pretty.

1. First the ckeditor5 packages needs to be in node_modules (a yarn install is sufficient)
2. In PhpStorm configure a new library in File | Settings | Languages & Frameworks | JavaScript | Libraries, add a new library, which points to the folder node_modules/@ckeditor
3. Replace things like @param {module:engine/model/element~Element} modelElement by @param {module:engine/model/element} modelElement so that the default export is used for the content of the this.
4. Once the above is done, there is code autocompletion as expected.

I don't think we can have a working out of the box experience for IDE autocompletion.

This is specific to jetbrains IDE but they're broadly used in the community so here goes a list of relevant issues about jsdoc & modules in webstorm:

• JSDoc inspection fails when module is not imported the same way it is exported (ES6/node) (possibly the root cause)
• JSDoc @module feature does not work as supposed to
• JSDoc @module unrecognized if imported from NPM dependency
• Document type class from particular module
• No auto complete suggestions for exports of ts import in jsdoc

Spent some time with lauriii looking at the issue.

What works in PhpStorm:

1. Associate the file type *.jsdoc as javascript files
2. Create an intermediate type that maps to the Ckeditor module:
   

   /**
    * @typedef {module:engine/model/element} module:engine/model/element~Element
    */
   

   This takes advantage of the fact that referencing {module:engine/model/element} makes the autocompletion work while keeping the same declaration that ckeditor folks have in their code.

I'll work on automatically generating a mapping for ckeditor types so we can provide a ckeditor5.types.jsdoc file that will make IDE autocompletion work as intended.

yolo solution, need more docs to explain what's happening but should be somewhat helping.

tweaked the regex, only 86 files ignored from the ckeditor source. I think I caught all the export default, and @interface alias declarations in the code.

The files that don't match are files with several exports.

[10:04:07] CKEditor5 types have been generated: 490 declarations aliased, 86 files ignored
Done in 0.10s.

Also we can just get rid of it altogether when IDEs become "smart enough" :)

This is a clever solution. Cksource has a proprietary doc generation standard (Umberto) that IDEs such as PHPStorm do not currently support. The ckeditor5-types-
‎documentation.js‎ script scans the contents of node_modules/@ckeditor5 for Umberto definitions. These definitions are used to dynamically generate a file - ckeditor5.types.jsdoc - that uses JSDoc to map IDE-understood typedefs to their actual definitions in CKEditor5. ckeditor5.types.jsdoc needs to be recognized as a JavaScript file in order to work so the IDE knows to parse the mapping as JSDoc.

This is a big DX improvement. It has zero impact on any runtime code so introducing these improvements now introduces no risk or debt. It can be improved on later if we wish, or we can just enjoy the considerable improvements introduced here.

Will commit once tests complete after the rebase I just performed.

Although it's likely quite safe for a number of reasons, I'm reluctant to Gitlab-merge an MR that needs rebasing until after the tests have fully run post-rebase.

Unfortunately, I keep missing the window between tests passing and not needing another rebase (the window often closes while tests run), so here's a patch of the current MR that I'll be using to commit this to D10.

Committed to 10.0.x, very nice addition.

Will see if 9.4.x is cherry pickable.

Cherry picked to 9.4.x.

Re-opening for 9.3.x backport.

Patch from local chery-pick.