瀏覽代碼

Docs: added docs for enableEngineDebug.

Szymon Cofalik 8 年之前
父節點
當前提交
34c7d9abc9
共有 1 個文件被更改,包括 53 次插入1 次删除
  1. 53 1
      packages/ckeditor5-engine/src/dev-utils/enableenginedebug.js

+ 53 - 1
packages/ckeditor5-engine/src/dev-utils/enableenginedebug.js

@@ -40,7 +40,46 @@ const maxTreeDumpLength = 20;
 let enabled = false;
 let log = console.log;
 
-export default function enableEngineDebug( logger ) {
+/**
+ * Enhances model classes with logging classes. Returns a plugin that should be loaded in the editor to
+ * enable debugging features.
+ *
+ * Every operation applied on {@link module:engine/model/document~Document model.Document} is logged.
+ *
+ * Following classes are expanded with `log` and meaningful `toString` methods:
+ * * {@link module:engine/model/position~Position model.Position},
+ * * {@link module:engine/model/range~Range model.Range},
+ * * {@link module:engine/model/text~Text model.Text},
+ * * {@link module:engine/model/element~Element model.Element},
+ * * {@link module:engine/model/rootelement~RootElement model.RootElement},
+ * * {@link module:engine/model/documentfragment~DocumentFragment model.DocumentFragment},
+ * * {@link module:engine/model/document~Document model.Document},
+ * * all {@link module:engine/model/operation/operation~Operation operations}
+ * * all {@link module:engine/model/delta/delta~Delta deltas},
+ * * {@link module:engine/view/element~Element view.Element},
+ * * {@link module:engine/view/documentfragment~DocumentFragment view.DocumentFragment},
+ * * {@link module:engine/view/document~Document view.Document}.
+ *
+ * Additionally, following logging utility methods are added:
+ * * {@link module:engine/model/text~Text model.Text} `logExtended`,
+ * * {@link module:engine/model/element~Element model.Element} `logExtended`,
+ * * {@link module:engine/model/element~Element model.Element} `logAll`,
+ * * {@link module:engine/model/delta/delta~Delta model.Delta} `logAll`.
+ *
+ * Additionally, following classes are expanded with `logTree` and `printTree` methods:
+ * * {@link module:engine/model/element~Element model.Element},
+ * * {@link module:engine/model/documentfragment~DocumentFragment model.DocumentFragment},
+ * * {@link module:engine/view/element~Element view.Element},
+ * * {@link module:engine/view/documentfragment~DocumentFragment view.DocumentFragment}.
+ *
+ * Finally, following methods are added to {@link module:core/editor/editor~Editor}: `logModel`, `logView`, `logDocuments`.
+ * All those methods take one parameter, which is a version of {@link module:engine/model/document~Document model document}
+ * for which model or view document state should be logged.
+ *
+ * @param {Function} [logger] Function used to log messages. By default messages are logged to console.
+ * @returns {module:engine/dev-utils/enableenginedebug~DebugPlugin} Plugin to be loaded in the editor.
+ */
+export default function enableEngineDebug( logger = console.log ) {
 	if ( logger ) {
 		log = logger;
 	}
@@ -379,6 +418,9 @@ function enableDocumentTools() {
 	}
 }
 
+/**
+ * Plugin that enables debugging features on the editor's model and view documents.
+ */
 class DebugPlugin extends Plugin {
 	constructor( editor ) {
 		super( editor );
@@ -399,6 +441,7 @@ class DebugPlugin extends Plugin {
 	}
 }
 
+// Helper function, stores `document` state for given `version` as a string in private property.
 function dumpTrees( document, version ) {
 	let string = '';
 
@@ -415,12 +458,18 @@ function dumpTrees( document, version ) {
 	}
 }
 
+// Helper function, returns class name of given `Delta` or `Operation`.
+// @param {module:engine/model/delta/delta~Delta|module:engine/model/operation/operation~Operation}
+// @returns {String} Class name.
 function getClassName( obj ) {
 	const path = obj.constructor.className.split( '.' );
 
 	return path[ path.length - 1 ];
 }
 
+// Helper function, converts map to {"key1":"value1","key2":"value2"} format.
+// @param {Map} map Map to convert.
+// @returns {String} Converted map.
 function mapString( map ) {
 	const obj = {};
 
@@ -431,6 +480,9 @@ function mapString( map ) {
 	return JSON.stringify( obj );
 }
 
+// Helper function, converts map to key1="value1" key2="value1" format.
+// @param {Map} map Map to convert.
+// @returns {String} Converted map.
 function mapToTags( map ) {
 	let string = '';