Docs: update error handling documentations.

src/ckeditorerror.js

@@ -14,21 +14,38 @@ export const DOCUMENTATION_URL =
 	'https://ckeditor.com/docs/ckeditor5/latest/framework/guides/support/error-codes.html';
 
 /**
- * The CKEditor error class.
+ * The CKEditor error class. Throw `CKEditorError` when:
  *
- * All errors will be shortened during the minification process in order to reduce the code size.
- * Therefore, all error messages should be documented in the same way as those in {@link module:utils/log}.
+ *  - an unexpected situation occurred and the editor most probably will not work properly. Such exception will be handled
+ *  by the {@link module:watchdog/watchdog~Watchdog watchdog}, if it is integrated, which will restart the editor,
  *
- * Read more in the {@link module:utils/log} module.
+ *  - if the initialization of the editor is incorrect or the editor API is used in the wrong way. This way you will give
+ *  feedback to the developer as soon as possible. Keep in mind that for common integration issues which do not
+ *  stop editor initialization (like missing adapter, wrong name of a toolbar component) we use `console.warn` with
+ *  {@link module:utils/ckeditorerror~attachLinkToDocumentation} to improve developers experience and let him see the
+ *  working editor as soon as possible.
+ *
+ * All errors will be shortened during the minification process in order to reduce the code size. Because of it, they
+ * should be documented in the following way:
+ *
+ *		/**
+ *		 * Error thrown when a plugin cannot be loaded due to JavaScript errors, lack of plugins with a given name, etc.
+ *		 *
+ *		 * @error plugin-load
+ *		 * @param pluginName The name of the plugin that could not be loaded.
+ *		 * @param moduleName The name of the module which tried to load this plugin.
+ *		 * /
+ *		throw new CKEditorError( 'plugin-load: It was not possible to load the "{$pluginName}" plugin in module "{$moduleName}', {
+ *			pluginName: 'foo',
+ *			moduleName: 'bar'
+ *		} );
  *
  * @extends Error
  */
 export default class CKEditorError extends Error {
 	/**
 	 * Creates an instance of the CKEditorError class.
 	 *
-	 * Read more about error logging in the {@link module:utils/log} module.
-	 *
 	 * @param {String} message The error message in an `error-name: Error message.` format.
 	 * During the minification process the "Error message" part will be removed to limit the code size
 	 * and a link to this error documentation will be added to the `message`.
@@ -79,7 +96,23 @@ export default class CKEditorError extends Error {
 }
 
 /**
- * Attaches link to the documentation at the end of the error message.
+ * Attaches the link to the documentation at the end of the error message. Use, whenever you log a warning or error on the
+ * console. It is also used by {@link module:utils/ckeditorerror~CKEditorError}.
+ *
+ * You should use `console.warn` together with this method to let developers know that he is integrating the editor or
+ * a plugin in a wrong way, without preventing the editor loading, for instance, the developer is using deprecated API,
+ * does not add an upload adapted or want to add not unavailable competent to the toolbar. You should not use console
+ * warning for errors addressed to end-users.
+ *
+ *		 /**
+ *		  * There was a problem processing the configuration of the toolbar. The item with the given
+ *		  * name does not exist so it was omitted when rendering the toolbar.
+ *		  *
+ *		  * @error toolbarview-item-unavailable
+ *		  * @param {String} name The name of the component.
+ *		  * /
+ *		 console.warn( attachLinkToDocumentation(
+ *		 	'toolbarview-item-unavailable: The requested toolbar item is unavailable.' ), { name } );
  *
  * @param {String} message Message to be logged.
  * @returns {String}