Ckeditor5: Errors documentation

[Reinmar]

(The mechanisms described in this issue were originally designed in https://github.com/ckeditor/ckeditor5-design/issues/14.)

Since the beginning, we mark every error with /** @error */ docstring containing additional information about the issue. E.g.:

/**
 * 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.
 *
 * This warning usually shows up when the {@link module:core/plugin~Plugin} which is supposed
 * to provide a toolbar item has not been loaded or there is a typo in the configuration.
 *
 * Make sure the plugin responsible for this toolbar item is loaded and the toolbar configuration
 * is correct, e.g. {@link module:basic-styles/bold~Bold} is loaded for the `'bold'` toolbar item.
 *
 * @error toolbarview-item-unavailable
 * @param {String} name The name of the component.
 */
log.warn(
    'toolbarview-item-unavailable: The requested toolbar item is unavailable.',
    { name }
);

Or:

/**
 * Command does not exist.
 *
 * @error commandcollection-command-not-found
 * @param {String} commandName Name of the command.
 */
throw new CKEditorError( 'commandcollection-command-not-found: Command does not exist.', { commandName } );

This was meant to allow us to keep error names short (and even minify them, by stripping the text after :). However, the crucial point here is to have these errors listed (with full descriptions) in the API docs site. Also, when CKEditorError or log.* are used, they should log also a working link to that error.

This means writing some kind of plugin for JSDoc or Umberto and figuring out how these errors should be listed. On one page in some special subpage? In the modules in which they are defined? What if an error may be thrown by multiple modules? This we need to answer first.

Secondly, later on, we can think on the following improvements:

• minifying the error names (as mentioned above – by stripping the textual part and leaving error code only) – ticket: https://github.com/ckeditor/ckeditor5/issues/30,
• validation that all errors (CKEditorError and log.* usage) are documented.

[Reinmar]

I realised how important is this documentation (from a day one) when working on https://github.com/ckeditor/ckeditor5-ui/pull/292. We may log and throw many things, but unless we document them extensively, they will be quite useless information (one need to google which doesn't always work and increases frustration).

[Reinmar]

cc @wwalc @m-turek @ma2ciek @pomek

[oleq]

This means writing some kind of plugin for JSDoc or Umberto and figuring out how these errors should be listed. On one page in some special subpage? In the modules in which they are defined? What if an error may be thrown by multiple modules? This we need to answer first.

This is a must-have thing, that's for sure. As to how to do this... I think both errors and warnings should be listed in a separate place, just like Google Maps errors or node.js error codes.

We could have 2 last custom items in the API documentation tree called "Error messages" and "Warning messages". Of course, this requires some additional work but as a developer, I'd rather expect things aggregated in one place than distributed across numerous packages.

TBH, as an off-topic, developers will probably also expect the complete configuration to be documented in one place. ATM they need to go to https://ckeditor5.github.io/docs/nightly/ckeditor5/latest/api/module_core_editor_editorconfig-EditorConfig.html and then navigate further to find out what is configurable. It's pretty annoying.

[wwalc]

I'd rather expect things aggregated in one place than distributed across numerous packages.

Me too, even with the assumption that usually one will just enter the error in the search box and then will be redirected to the proper page.

Reasons for grouping:

• One can also learn something just by looking at the other possible error messages and their explanations. Having them in one place encourages such actions.
• We will be sure that the search engine will redirect the user to the error documentation when he starts looking for anything related to errors, as a single page in the documentation will have high score for similar searches.

TBH, as an off-topic, developers will probably also expect the complete configuration to be documented in one place. ATM they need to go to https://ckeditor5.github.io/docs/nightly/ckeditor5/latest/api/module_core_editor_editorconfig-EditorConfig.html and then navigate further to find out what is configurable. It's pretty annoying.

I think it's already fine what we have there. Usually one will not be changing dozens of options, this is actually what we want to change in CKEditor 5.

[Reinmar]

OK, so aggregated they will be. 🌮

[ma2ciek]

I can try to write a plugin for the JSDoc to gather all errors and add a throws field in methods that throw some known errors. I'm not sure whether this would be an easy task. Docs for JSDoc aren't great as we all know :D

Enhancing the JSDoc in such way should provide an easy-to-use output for Umberto.

PS: JSDoc provides a throws tag for functions - http://usejsdoc.org/tags-throws.html. Aren't we reinventing the wheel?

[Reinmar]

PS: JSDoc provides a throws tag for functions - http://usejsdoc.org/tags-throws.html. Aren't we reinventing the wheel?

Not really. We don't want to document the API here. We want to document the potential errors which the whole application may produce. E.g. some warnings are not produced by any particular method but rather some state's observers.

and add a throws field in methods that throw some known errors.

Not necessary. Let's focus on creating the list of errors.

[ma2ciek]

Not necessary. Let's focus on creating the list of errors.

Ok. I tested the custom tags once and this should be possible and quite ease to achieve.