{"action":"opened","issue":{"url":"https://api.github.com/repos/ckeditor/ckeditor5-dev/issues/280","repository_url":"https://api.github.com/repos/ckeditor/ckeditor5-dev","labels_url":"https://api.github.com/repos/ckeditor/ckeditor5-dev/issues/280/labels{/name}","comments_url":"https://api.github.com/repos/ckeditor/ckeditor5-dev/issues/280/comments","events_url":"https://api.github.com/repos/ckeditor/ckeditor5-dev/issues/280/events","html_url":"https://github.com/ckeditor/ckeditor5-dev/issues/280","id":257040391,"number":280,"title":"Errors documentation","user":{"login":"Reinmar","id":156149,"avatar_url":"https://avatars2.githubusercontent.com/u/156149?v=4","gravatar_id":"","url":"https://api.github.com/users/Reinmar","html_url":"https://github.com/Reinmar","followers_url":"https://api.github.com/users/Reinmar/followers","following_url":"https://api.github.com/users/Reinmar/following{/other_user}","gists_url":"https://api.github.com/users/Reinmar/gists{/gist_id}","starred_url":"https://api.github.com/users/Reinmar/starred{/owner}{/repo}","subscriptions_url":"https://api.github.com/users/Reinmar/subscriptions","organizations_url":"https://api.github.com/users/Reinmar/orgs","repos_url":"https://api.github.com/users/Reinmar/repos","events_url":"https://api.github.com/users/Reinmar/events{/privacy}","received_events_url":"https://api.github.com/users/Reinmar/received_events","type":"User","site_admin":false},"labels":[],"state":"open","locked":false,"assignee":null,"assignees":[],"milestone":null,"comments":0,"created_at":"2017-09-12T13:20:05Z","updated_at":"2017-09-12T13:20:05Z","closed_at":null,"author_association":"OWNER","body":"Since the beginning, we mark every error with `/** @error */` docstring containing additional information about the issue. E.g.:\r\n\r\n```js\r\n\t\t\t\t/**\r\n\t\t\t\t * There was a problem processing the configuration of the toolbar. The item with the given\r\n\t\t\t\t * name does not exist so it was omitted when rendering the toolbar.\r\n\t\t\t\t *\r\n\t\t\t\t * This warning usually shows up when the {@link module:core/plugin~Plugin} which is supposed\r\n\t\t\t\t * to provide a toolbar item has not been loaded or there is a typo in the configuration.\r\n\t\t\t\t *\r\n\t\t\t\t * Make sure the plugin responsible for this toolbar item is loaded and the toolbar configuration\r\n\t\t\t\t * is correct, e.g. {@link module:basic-styles/bold~Bold} is loaded for the `'bold'` toolbar item.\r\n\t\t\t\t *\r\n\t\t\t\t * @error toolbarview-item-unavailable\r\n\t\t\t\t * @param {String} name The name of the component.\r\n\t\t\t\t */\r\n\t\t\t\tlog.warn(\r\n\t\t\t\t\t'toolbarview-item-unavailable: The requested toolbar item is unavailable.',\r\n\t\t\t\t\t{ name }\r\n\t\t\t\t);\r\n```\r\n\r\nOr:\r\n\r\n```js\r\n\t\t\t/**\r\n\t\t\t * Command does not exist.\r\n\t\t\t *\r\n\t\t\t * @error commandcollection-command-not-found\r\n\t\t\t * @param {String} commandName Name of the command.\r\n\t\t\t */\r\n\t\t\tthrow new CKEditorError( 'commandcollection-command-not-found: Command does not exist.', { commandName } );\r\n```\r\n\r\nThis 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.\r\n\r\nThis 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.\r\n\r\nSecondly, later on, we can think of the following improvements:\r\n\r\n* minifying the error names (as mentioned above – by stripping the textual part and leaving error code only),\r\n* validation that all errors (`CKEditorError` and `log.*` usage) are documented.\r\n\r\n"}}
{"actor":{"display_login":"Reinmar"}}