log.js 2.8 KB

12345678910111213141516171819202122232425262728293031323334353637383940414243444546474849505152535455565758596061626364656667686970717273747576
  1. /**
  2. * @license Copyright (c) 2003-2019, CKSource - Frederico Knabben. All rights reserved.
  3. * For licensing, see LICENSE.md.
  4. */
  5. /* global console */
  6. /**
  7. * @module utils/log
  8. */
  9. import { attachLinkToDocumentation } from './ckeditorerror';
  10. /**
  11. * The logging module.
  12. *
  13. * This object features two functions that should be used across CKEditor code base to log errors and warnings.
  14. * Despite being an overridable interface for native `console.*` this module serves also the goal to limit the
  15. * code size of a minified CKEditor package. During minification process the messages will be shortened and
  16. * links to their documentation will be logged to the console.
  17. *
  18. * All errors and warning should be documented in the following way:
  19. *
  20. * /**
  21. * * Error thrown when a plugin cannot be loaded due to JavaScript errors, lack of plugins with a given name, etc.
  22. * *
  23. * * @error plugin-load
  24. * * @param pluginName The name of the plugin that could not be loaded.
  25. * * @param moduleName The name of the module which tried to load this plugin.
  26. * * /
  27. * log.error( 'plugin-load: It was not possible to load the "{$pluginName}" plugin in module "{$moduleName}', {
  28. * pluginName: 'foo',
  29. * moduleName: 'bar'
  30. * } );
  31. *
  32. * ### Warning vs Error vs Throw
  33. *
  34. * * Whenever a potentially incorrect situation occurs, which does not directly lead to an incorrect behavior,
  35. * log a warning.
  36. * * Whenever an incorrect situation occurs, but the app may continue working (although perhaps incorrectly),
  37. * log an error.
  38. * * Whenever it's really bad and it does not make sense to continue working, throw a {@link module:utils/ckeditorerror~CKEditorError}.
  39. *
  40. * @namespace
  41. */
  42. const log = {
  43. /**
  44. * Logs an error to the console.
  45. *
  46. * Read more about error logging in the {@link module:utils/log} module.
  47. *
  48. * @param {String} message The error message in an `error-name: Error message.` format.
  49. * During the minification process the "Error message" part will be removed to limit the code size
  50. * and a link to this error documentation will be logged to the console.
  51. * @param {Object} [data] Additional data describing the error.
  52. */
  53. error( message, data ) {
  54. console.error( attachLinkToDocumentation( message ), data );
  55. },
  56. /**
  57. * Logs a warning to the console.
  58. *
  59. * Read more about error logging in the {@link module:utils/log} module.
  60. *
  61. * @param {String} message The warning message in a `warning-name: Warning message.` format.
  62. * During the minification process the "Warning message" part will be removed to limit the code size
  63. * and a link to this error documentation will be logged to the console.
  64. * @param {Object} [data] Additional data describing the warning.
  65. */
  66. warn( message, data ) {
  67. console.warn( attachLinkToDocumentation( message ), data );
  68. }
  69. };
  70. export default log;