Added and improved DocTest api docstrings. (d0402d1e) · Commits · extjs / jsduck

template/app/controller/DocTests.js

+29 −6

Original line number	Diff line number	Diff line
		@@ -4,10 +4,27 @@
		Ext.define('Docs.controller.DocTests', {
		extend: 'Docs.controller.Content',
		requires: ['Ext.data.Store', 'Docs.model.DocTest'],
		baseUrl: "#!/doctests",

		/**
		* @cfg
		* Regex used to locate all <pre> nodes.
		* @private
		*/
		preRegex: /<pre[\s\S]?>[\s\S]?<\/pre[\s\S]*?>/gi,


		/**
		* @cfg
		* Regex used to determine if a node is an inline example.
		* @private
		*/
		preClsRegex: /class=[\s\S]*?inline-example/i,

		/**
		* @cfg
		* Regex used to locate <code> node.
		* @private
		*/
		codeRegex: /<code[\s\S]?>[\s\S]+?<\/code[\s\S]?>/gi,

		refs: [
		@@ -56,8 +73,8 @@ Ext.define('Docs.controller.DocTests', {
		/**
		* Locates all examples.
		*
		* @param {Ext.data.Store} store The data store used to populate the grid.
		* @private
		* @param {Ext.data.Store}
		*/
		locateExamples: function(store) {
		this.clssLeft = Docs.data.doctests.length;
		@@ -75,9 +92,9 @@ Ext.define('Docs.controller.DocTests', {
		/**
		* Locates all inline examples attached to a class file.
		*
		* @param {Ext.data.Store} store The data store used to populate the grid.
		* @param {String} cls The Ext class name being interrogated.
		* @private
		* @param {Ext.data.Store}
		* @param {Object}
		*/
		locateClsExamples: function(store, cls) {
		var baseUrl = this.getBaseUrl() + '/output/',
		@@ -123,8 +140,8 @@ Ext.define('Docs.controller.DocTests', {
		/**
		* Extract example code from html.
		*
		* @param {String} html The html being parsed.
		* @private
		* @param {String}
		*/
		extractExampleCode: function(html) {
		var exampleCodes = [],
		@@ -141,6 +158,12 @@ Ext.define('Docs.controller.DocTests', {
		return exampleCodes;
		},

		/**
		* Called after view's grid is rendered.
		*
		* @param {Ext.grid.Panel} grid The grid panel that was rendered.
		* @private
		*/
		onGridAfterRender: function(grid) {
		var store = grid.getStore();
		this.locateExamples(store);

template/app/view/doctests/Index.js

+66 −20

Original line number	Diff line number	Diff line
		@@ -107,6 +107,7 @@ Ext.define('Docs.view.doctests.Index', {

		/**
		* Returns tab config for the doctests page.
		*
		* @return {Object}
		*/
		getTab: function() {
		@@ -115,20 +116,23 @@ Ext.define('Docs.view.doctests.Index', {
		},

		/**
		* Executes an example
		* Executes an example.
		*
		* @param {Object} config The test configuration.
		* @private
		*/
		runExample: function(tests) {
		if (!tests.examples \|\| tests.examples.length < 1) {
		runExample: function(config) {
		if (!config.examples \|\| config.examples.length < 1) {
		return;
		}

		if ((!tests.fail) && (!tests.pass)) {
		if ((!config.fail) && (!config.pass)) {
		Ext.ComponentQuery.query('#testcontainer', this)[0].setDisabled(true);
		}

		this.clearTestRunner();
		var testRunner = this.getComponent('testrunner');
		var record = tests.examples.pop();
		var record = config.examples.pop();

		var example = testRunner.add(
		Ext.create('Docs.view.examples.Inline', {
		@@ -137,38 +141,56 @@ Ext.define('Docs.view.doctests.Index', {
		})
		);

		example.on('previewsuccess', Ext.bind(this.onPreviewSuccess, this, [record, tests], true), this);
		example.on('previewfailure', Ext.bind(this.onPreviewFailure, this, [record, tests], true), this);
		example.on('previewsuccess', Ext.bind(this.onPreviewSuccess, this, [record, config], true), this);
		example.on('previewfailure', Ext.bind(this.onPreviewFailure, this, [record, config], true), this);
		example.showPreview();
		},

		/**
		* Removes child elements from testrunner component.
		*
		* @private
		*/
		clearTestRunner: function() {
		var testRunner = this.getComponent('testrunner');
		testRunner.removeAll();
		},

		showResult: function(tests) {
		/**
		* Renders test result to dom.
		*
		* @param {Object} config The test configuration.
		* @private
		*/
		showResult: function(config) {
		var cls = 'doc-test-success',
		total = tests.pass + tests.fail,
		total = config.pass + config.fail,
		testControls = this.getComponent('testcontainer').getComponent('testcontrols');

		if (tests.fail) {
		if (config.fail) {
		cls = 'doc-test-failure';
		}

		testControls.remove('testResult');
		testControls.insert(0, {
		itemId: 'testResult',
		html: '<span class="' + cls + '">' + tests.fail.toString() + '/' + total.toString() + ' tests failed</span>'
		html: '<span class="' + cls + '">' + config.fail.toString() + '/' + total.toString() + ' tests failed</span>'
		});

		if (tests.examples.length < 1) {
		if (config.examples.length < 1) {
		Ext.ComponentQuery.query('#testcontainer', this)[0].setDisabled(false);
		} else {
		this.runExample(tests);
		this.runExample(config);
		}
		},

		/**
		* Run link click handler.
		*
		* @param {Ext.grid.Panel} grid The grid that was clicked.
		* @param {Docs.model.DocTest} record The record that was clicked.
		* @private
		*/
		onRunLinkClick: function(grid, record) {
		this.runExample({
		pass: 0,
		@@ -177,6 +199,11 @@ Ext.define('Docs.view.doctests.Index', {
		});
		},

		/**
		* RunAll button click handler.
		*
		* @private
		*/
		onRunAllButtonClick: function() {
		var examples = [];
		this.store.each(function(record) {
		@@ -189,18 +216,37 @@ Ext.define('Docs.view.doctests.Index', {
		});
		},

		onPreviewSuccess: function(preview, obj, record, tests) {
		/**
		* previewsuccess event handler
		*
		* @param {Ext.Component} preview The preview component.
		* @param {Object} options The event options.
		* @param {Docs.model.DocTest} record The successful record.
		* @param {Object} config The test configuration.
		* @private
		*/
		onPreviewSuccess: function(preview, options, record, config) {
		this.clearTestRunner();
		record.set('status', '<span class="doc-test-success">pass</span>');
		tests.pass++;
		this.showResult(tests);
		config.pass++;
		this.showResult(config);

		if (Ext.isDefined(console)) {
		console.log('Test passed: ', record.get('name'));
		}
		},

		onPreviewFailure: function(preview, e, obj, record, tests) {
		/**
		* previewfailure event handler
		*
		* @param {Ext.Component} preview The preview component.
		* @param {Error} error The Error thrown during the example.
		* @param {Object} options The event options.
		* @param {Docs.model.DocTest} record The successful record.
		* @param {Object} config The test configuration.
		* @private
		*/
		onPreviewFailure: function(preview, e, obj, record, config) {
		this.clearTestRunner();

		if (e.docAssertFailed) {
		@@ -210,8 +256,8 @@ Ext.define('Docs.view.doctests.Index', {
		}

		record.set('message', '(exception logged to console): ' + e.toString());
		tests.fail++;
		this.showResult(tests);
		config.fail++;
		this.showResult(config);

		if (Ext.isDefined(console)) {
		var stack = 'no stack available';

template/app/view/examples/Inline.js

+3 −3

Original line number	Diff line number	Diff line
		@@ -43,14 +43,14 @@ Ext.define('Docs.view.examples.Inline', {
		/**
		* @event previewsuccess
		* Fired when preview was successfully created.
		* @param {Ext.Component} this
		* @param {Ext.Component} preview
		*/
		'previewsuccess',
		/**
		* @event previewfailure
		* Fired when preview contains an error.
		* @param {Ext.Component} this
		* @param {Error} exception
		* @param {Ext.Component} preview
		* @param {Error} e
		*/
		'previewfailure',
		]);

template/app/view/examples/InlinePreview.js

+37 −9

Original line number	Diff line number	Diff line
		@@ -10,21 +10,49 @@ Ext.define('Docs.view.examples.InlinePreview', {
		bodyPadding: '0 10',

		statics: {
		/**
		* @private
		*/
		iframeId: 0,

		/**
		* Returns the next available iframeId.
		*
		* @return {String} iframeId
		* @private
		*/
		getNextIframeId: function() {
		return this.iframeId++;
		this.iframeId++;
		return this.iframeId.toString();
		},

		/**
		* Returns the preview component with the matching iframeId.
		*
		* @param {String} iframeId
		* @return {Ext.Component}
		* @private
		*/
		getPreviewByIframeId: function(iframeId) {
		return Ext.ComponentManager.get('inline-preview-' + iframeId);
		return Ext.ComponentManager.get('inline-preview-' + iframeId.toString());
		},

		/**
		* Called when an preview has been successfully executed.
		*
		* @param {String} iframeId
		*/
		previewSuccess: function(iframeId) {
		var preview = this.getPreviewByIframeId(iframeId);
		preview.fireEvent('previewsuccess', preview);
		},

		/**
		* Called when an error occured during preview execution.
		*
		* @param {String} iframeId
		* @param {Error} e
		*/
		previewFailure: function(iframeId, e) {
		var preview = this.getPreviewByIframeId(iframeId);
		preview.fireEvent('previewfailure', preview, e);
		@@ -48,14 +76,14 @@ Ext.define('Docs.view.examples.InlinePreview', {
		/**
		* @event previewsuccess
		* Fired when preview was successfully created.
		* @param {Ext.Component} this
		* @param {Ext.Component} preview
		*/
		'previewsuccess',
		/**
		* @event previewfailure
		* Fired when preview contains an error.
		* @param {Ext.Component} this
		* @param {Error} exception
		* @param {Ext.Component} preview
		* @param {Error} e
		*/
		'previewfailure'
		]);