Write ESLint rule for CKEditorError's

[Reinmar]

📝 Provide a description of the improvement

• A few links miss the :Error message part #5643
• Missing @error.
  • This one is tricky as the error definition may be in a different file. We may need to have some /** @error other-file-path... */ to reference them.

---

If you'd like to see this improvement implemented, add a 👍 reaction to this post.

[Reinmar]

I wanted to add this at the beginning of CKEditorError() but it fails in too many places (tests, most likely) for me to finish this:

		if ( !message.match( /[^:]+: [^.]+\./ ) ) {
			throw new Error( 'Wrong CKEditorError message format.' );
		}

[ma2ciek]

Optionally this could be a part of the documentation validator. But IMO the faster an error appears the better.

[ma2ciek]

We could also use https://eslint.org/docs/rules/valid-jsdoc for the default set of JSDoc tags.

[ma2ciek]

Oh, I saw it's deprecated.

[ma2ciek]

However, there's also a community plugin - https://github.com/gajus/eslint-plugin-jsdoc

[Reinmar]

I wonder if the part of the error after the colon is needed. I think I wanted it to be there so if you're having an error in the dev version of CKE5, you get the full title. But perhaps it's not needed anymore? Although, if an error is described only by its id and has no definition in  @error (because someone forgot to write it), then figuring out what it means may be tricky.

So, having @errors for all errors would be more important in this case.

[Reinmar]

In the past, I wrote that the message description in the error itself is necessary (#5643 (comment)) but now I think that it's overhead. I think that we could remove that bit from all errors and improve their error codes and error doc strings.

It'd be like:

/**
 * The {@link module:utils/collection~Collection#add `Collection#add()`} method was called without
 * an item. This method always needs to be executed with an item. And so on...
 *
 * @error collection-add-called-without-an-item
 */
throw new CKEditorError( 'collection-add-called-without-an-item', this );

Instead of:

/**
 * Missing item.
 *
 * @error collection-add-invalid-call
 */
throw new CKEditorError( 'collection-add-invalid-call: Missing item.', this );

The latter example looks like many errors that we have. The id (`collection-add-invalid-call`) does not help you understand what happened. The message that follows is often poor as well. And the documentation does not extend the error. 

We can remove the message if we'll focus on making the ids clearer. And the documentation should clearly explain what was wrong and how to do that right (if possible).

[Reinmar]

cc @AnnaTomanek @oleq ☝️

[Reinmar]

cc @jodator ☝️