Document code with JSDuck

Change-Id: Ieb812a2fb85135f6db18a9a02c94efd83695a19e

.gitignore

@@ -2,6 +2,7 @@
 *~
 *.kate-swp
 .*.swp
+/docs
 node_modules
 composer.lock
 vendor

jsduck.external.js

@@ -0,0 +1,14 @@
+/**
+ * @class jQuery
+ * <http://api.jquery.com/>
+ */
+
+/**
+ * @class jQuery.Event
+ * <http://api.jquery.com/Types/#Event>
+ */
+
+/**
+ * @class jQuery.Promise
+ * <http://api.jquery.com/Types/#Promise>
+ */

jsduck.json

@@ -0,0 +1,11 @@
+{
+	"--title": "TemplateData - Documentation",
+	"--processes": "0",
+	"--warnings-exit-nonzero": true,
+	"--external": "OO.*",
+	"--output": "docs",
+	"--": [
+		"jsduck.external.js",
+		"modules"
+	]
+}

modules/ext.templateDataGenerator.data.js

@@ -1,5 +1,9 @@
 /**
  * TemplateData Dialog
+ * @class
+ * @mixins OO.EventEmitter
+ *
+ * @constructor
  * @param {Object} config Dialog configuration object
  */
 mw.TemplateData.Model = function mwTemplateDataModel( config ) {

modules/ext.templateDataGenerator.editPage.js

@@ -1,5 +1,5 @@
 ( function () {
-	/**
+	/*!
 	 * TemplateData Generator button fixture
 	 * The button will appear on Template namespaces only, above the edit textbox
 	 *

modules/ext.templateDataGenerator.ui.js

@@ -1,33 +1,31 @@
 ( function () {
+	'use strict';
 	/**
 	 * TemplateData Generator data model.
 	 * This singleton is independent of any UI; it expects
 	 * a templatedata string, converts it into the object
 	 * model and manages it, fully event-driven.
 	 *
-	 * @author Moriel Schottlender
+	 * @class
+	 * @singleton
 	 */
-	'use strict';
 	mw.libs.tdgUi = ( function () {
 		var isPageSubLevel,
 			isDocPage,
 			pageName,
 			parentPage,
 			$textbox,
-			/**
-			 * ooui Window Manager
-			 */
+			// ooui Window Manager
 			tdgDialog,
 			windowManager,
-			/**
-			 * Edit window elements
-			 */
+			// Edit window elements
 			editOpenDialogButton,
 			editNoticeLabel,
 
 		editArea = {
 			/**
 			 * Display error message in the edit window
+			 *
 			 * @param {string} msg Message to display
 			 * @param {string} type Message type 'notice' or 'error'
 			 * @param {boolean} [parseHTML] The message should be parsed
@@ -57,6 +55,8 @@
 
 		/**
 		 * Respond to edit dialog button click.
+		 *
+		 * @method onEditOpenDialogButton
 		 */
 		onEditOpenDialogButton = function () {
 			// Reset notice message
@@ -73,6 +73,8 @@
 
 		/**
 		 * Respond to edit dialog apply event
+		 *
+		 * @method onDialogApply
 		 * @param {string} templateDataString New templatedata string
 		 */
 		onDialogApply = function ( templateDataString ) {
@@ -82,6 +84,8 @@
 		/**
 		 * Replace the old templatedata string with the new one, or
 		 * insert the new one into the page if an old one doesn't exist
+		 *
+		 * @method replaceTemplateData
 		 * @param {string} newTemplateData New templatedata string
 		 * @return {string} Full wikitext content with the new templatedata
 		 *  string.

modules/ext.templateDataGenerator.ui.tdDialog.js

@@ -1,5 +1,10 @@
 /**
  * TemplateData Dialog
+ *
+ * @class
+ * @extends OO.ui.ProcessDialog
+ *
+ * @constructor
  * @param {Object} config Dialog configuration object
  */
 mw.TemplateData.Dialog = function mwTemplateDataDialog( config ) {
@@ -56,7 +61,14 @@ mw.TemplateData.Dialog.static.actions = [
 ];
 
 /**
- * @inheritdoc
+ * Initialize window contents.
+ *
+ * The first time the window is opened, #initialize is called so that changes to the window that
+ * will persist between openings can be made. See #getSetupProcess for a way to make changes each
+ * time the window opens.
+ *
+ * @throws {Error} If not attached to a manager
+ * @chainable
  */
 mw.TemplateData.Dialog.prototype.initialize = function () {
 	var templateParamsFieldset, addParamFieldlayout, languageActionFieldLayout,
@@ -223,6 +235,10 @@ mw.TemplateData.Dialog.prototype.onModelChangeDescription = function ( descripti
 	this.descriptionInput.setValue( description );
 };
 
+/**
+ * Respond to add param input change.
+ * @param {string} value New parameter name
+ */
 mw.TemplateData.Dialog.prototype.onAddParamInputChange = function ( value ) {
 	var allProps = mw.TemplateData.Model.static.getAllProperties( true );
 
@@ -278,12 +294,18 @@ mw.TemplateData.Dialog.prototype.onModelAddKeyParamOrder = function ( key ) {
 	this.paramOrderWidget.addItems( [ dragItem ] );
 };
 
+/**
+ * Respond to param order widget reorder event
+ * @param {mw.TemplateData.DragDropItemWidget} item Item reordered
+ * @param {number} newIndex New index of the item
+ */
 mw.TemplateData.Dialog.prototype.onParamOrderWidgetReorder = function ( item, newIndex ) {
 	this.model.reorderParamOrderKey( item.getData(), newIndex );
 };
 
 /**
  * Respond to description input change event
+ * @param {string} value Description value
  */
 mw.TemplateData.Dialog.prototype.onDescriptionInputChange = function ( value ) {
 	if ( this.model.getTemplateDescription() !== value ) {
@@ -732,7 +754,9 @@ mw.TemplateData.Dialog.prototype.importParametersFromTemplateCode = function ()
 };
 
 /**
- * @inheritdoc
+ * Get a process for setting up a window for use.
+ *
+ * @param {Object} [data] Dialog opening data
  */
 mw.TemplateData.Dialog.prototype.getSetupProcess = function ( data ) {
 	return mw.TemplateData.Dialog.super.prototype.getSetupProcess.call( this, data )
@@ -874,7 +898,10 @@ mw.TemplateData.Dialog.prototype.switchPanels = function ( panel ) {
 };
 
 /**
- * @inheritdoc
+ * Get a process for taking action.
+ *
+ * @param {string} [action] Symbolic name of action
+ * @return {OO.ui.Process} Action process
  */
 mw.TemplateData.Dialog.prototype.getActionProcess = function ( action ) {
 	if ( action === 'back' ) {

modules/widgets/ext.templateDataGenerator.dragDropWidget.js

@@ -49,7 +49,7 @@ mw.TemplateData.DragDropWidget.prototype.getKeyArray = function () {
  * Reorder the key into its new index. Find the item first, then add
  * it back in its new place.
  * @param {string} key Unique key
- * @param {[type]} newIndex New index
+ * @param {number} newIndex New index
  */
 mw.TemplateData.DragDropWidget.prototype.reorderKey = function ( key, newIndex ) {
 	var i, len, item;

modules/widgets/ext.templateDataGenerator.languageSearchWidget.js

@@ -48,7 +48,11 @@ OO.inheritClass( mw.TemplateData.LanguageSearchWidget, OO.ui.SearchWidget );
 /* Methods */
 
 /**
- * @inheritdoc
+ * Handle select widget select events.
+ *
+ * Clears existing results. Subclasses should repopulate items according to new query.
+ *
+ * @param {string} value New value
  */
 mw.TemplateData.LanguageSearchWidget.prototype.onQueryChange = function () {
 	// Parent method

package.json

@@ -2,7 +2,8 @@
   "name": "templatedata",
   "version": "0.0.0",
   "scripts": {
-    "test": "grunt test"
+    "test": "grunt test",
+    "doc": "jsduck"
   },
   "repository": {
     "type": "git",