Use jsdoc for generating Minerva documentation

Given the level of documentation in this repo is extremely low now seems a good as time as any. The resulting documentation is a vast improvement on before grouping functions to an owner and introducing module names. We can iterate on the documentation over time. Bug: T138401 Change-Id: I9e787d40931d3d72a7037ce07d3ab0db8e72d825
2018-03-15 13:27:39 -07:00 · 2018-03-15 13:27:39 -07:00 · eaa2692da0
parent c18bcd67fd
commit eaa2692da0
9 changed files with 57 additions and 68 deletions
--- a/jsdoc.json
+++ b/jsdoc.json
@ -0,0 +1,22 @@
+{
+    "opts": {
+        "encoding": "utf8",
+        "destination": "docs",
+        "packageX": "package.json",
+        "readme": "README.md",
+        "recurse": true
+    },
+    "plugins": [],
+    "recurseDepth": 10,
+    "source": {
+        "include": [ "resources" ],
+        "includePattern": ".+\\.js$"
+    },
+    "tags": {},
+    "templates": {
+        "cleverLinks": true,
+        "default": {
+            "useLongnameInNav": true
+        }
+    }
+}
--- a/jsduck.json
+++ b/jsduck.json
@ -1,36 +0,0 @@
-{
-	"--title": "MinervaNeue - Documentation",
-	"--output": "docs",
-	"--processes": "0",
-	"--warnings-exit-nonzero": true,
-	"--builtin-classes": true,
-	"--external": [
-		"Hogan.Template",
-		"HandleBars.Template",
-		"jQuery.Deferred",
-		"jQuery.Promise",
-		"jQuery.Event",
-		"jQuery.Object",
-		"jqXHR",
-		"View",
-		"Page",
-		"Skin",
-		"File",
-		"Router",
-		"Icon",
-		"MainMenu",
-		"mw.user",
-		"mw.Api",
-		"mw.ForeignApi",
-		"OO.ui.ToolGroup",
-		"OO.ui.Tool",
-		"OO.ui.mixin.LookupElement",
-		"OO.EventEmitter",
-		"ve.init.mw.MobileArticleTarget",
-		"mw.echo.dm.NotificationItem"
-	],
-	"--warnings": ["-nodoc(class,public)", "-dup_member", "-link_ambiguous"],
-	"--": [
-		"resources"
-	]
-}
--- a/package-lock.json
+++ b/package-lock.json
@ -74,7 +74,7 @@
 		"ansi-escapes": {
 			"version": "3.0.0",
 			"resolved": "https://registry.npmjs.org/ansi-escapes/-/ansi-escapes-3.0.0.tgz",
-			"integrity": "sha512-O/klc27mWNUigtv0F8NJWbLF00OcegQalkqKURWdosW08YZKi4m6CnSUSvIZG1otNJbTWhN01Hhz389DW7mvDQ==",
+			"integrity": "sha1-7D6LTp+AZPwCw6ybZfHCdb2o75I=",
 			"dev": true
 		},
 		"ansi-regex": {
@ -107,7 +107,7 @@
 		"arr-flatten": {
 			"version": "1.1.0",
 			"resolved": "https://registry.npmjs.org/arr-flatten/-/arr-flatten-1.1.0.tgz",
-			"integrity": "sha512-L3hKV5R/p5o81R7O02IGnwpDmkp6E982XhtbuwSe3O4qOtMMMtodicASA1Cny2U+aCXcNpml+m4dPsvsJ3jatg==",
+			"integrity": "sha1-NgSLv/TntH4TZkQxbJlmnqWukfE=",
 			"dev": true
 		},
 		"array-differ": {
@ -337,13 +337,13 @@
 		"circular-json": {
 			"version": "0.3.3",
 			"resolved": "https://registry.npmjs.org/circular-json/-/circular-json-0.3.3.tgz",
-			"integrity": "sha512-UZK3NBx2Mca+b5LsG7bY183pHWt5Y1xts4P3Pz7ENTwGVnJOUWbRb3ocjvX7hx9tq/yTAdclXm9sZ38gNuem4A==",
+			"integrity": "sha1-gVyZ6oT2gJUp0vRXkb34JxE1LWY=",
 			"dev": true
 		},
 		"clap": {
 			"version": "1.2.3",
 			"resolved": "https://registry.npmjs.org/clap/-/clap-1.2.3.tgz",
-			"integrity": "sha512-4CoL/A3hf90V3VIEjeuhSvlGFEHKzOz+Wfc2IVZc+FaUgU0ZQafJTP49fvnULipOPcAfqhyI2duwQyns6xqjYA==",
+			"integrity": "sha1-TzZ0WzIAhJJVf0ZBLWbVDLmbzlE=",
 			"requires": {
 				"chalk": "1.1.3"
 			}
@ -528,7 +528,7 @@
 		"cosmiconfig": {
 			"version": "2.2.2",
 			"resolved": "https://registry.npmjs.org/cosmiconfig/-/cosmiconfig-2.2.2.tgz",
-			"integrity": "sha512-GiNXLwAFPYHy25XmTPpafYvn3CLAkJ8FLsscq78MQd1Kh0OU6Yzhn4eV2MVF4G9WEQZoWEGltatdR+ntGPMl5A==",
+			"integrity": "sha1-YXPOvVb6wELB9DkO33r2wHx8uJI=",
 			"dev": true,
 			"requires": {
 				"is-directory": "0.3.1",
@ -976,7 +976,7 @@
 		"eslint-config-wikimedia": {
 			"version": "0.5.0",
 			"resolved": "https://registry.npmjs.org/eslint-config-wikimedia/-/eslint-config-wikimedia-0.5.0.tgz",
-			"integrity": "sha512-m5NC4l7hk2+9j4Q7JILGbrANR2fIEO6HgnKrarKY3KgU7WQH/Yi2qQ/cujJNEDkIutYC8wFZ/0LDA7WEjLHatA==",
+			"integrity": "sha1-721DTprG061K5RDPne9GjEmKLjU=",
 			"dev": true
 		},
 		"eslint-scope": {
@ -1344,7 +1344,7 @@
 				"glob": {
 					"version": "7.1.2",
 					"resolved": "https://registry.npmjs.org/glob/-/glob-7.1.2.tgz",
-					"integrity": "sha512-MJTUg1kjuLeQCJ+ccE4Vpa6kKVXkPYJ2mOCQyUuKLcLQsdrMCpBPUi8qVE6+YuaJkozeA9NusTAw3hLr8Xe5EQ==",
+					"integrity": "sha1-wZyd+aAocC1nhhI4SmVSQExjbRU=",
 					"dev": true,
 					"requires": {
 						"fs.realpath": "1.0.0",
@ -1594,7 +1594,7 @@
 		"hosted-git-info": {
 			"version": "2.5.0",
 			"resolved": "https://registry.npmjs.org/hosted-git-info/-/hosted-git-info-2.5.0.tgz",
-			"integrity": "sha512-pNgbURSuab90KbTqvRPsseaTxOJCZBD0a7t+haSN33piP9cCM4l0CqdzAif2hUqm716UovKB2ROmiabGAKVXyg==",
+			"integrity": "sha1-bWDjSzq7yDEwYsO3mO+NkBoHrzw=",
 			"dev": true
 		},
 		"html-tags": {
@ -1671,7 +1671,7 @@
 		"inquirer": {
 			"version": "3.3.0",
 			"resolved": "https://registry.npmjs.org/inquirer/-/inquirer-3.3.0.tgz",
-			"integrity": "sha512-h+xtnyk4EwKvFWHrUYsWErEVR+igKtLdchu+o0Z1RL7VU/jVMFbYir2bp6bAj8efFNxWqHX0dIss6fJQ+/+qeQ==",
+			"integrity": "sha1-ndLyrXZdyrH/BEO0kUQqILoifck=",
 			"dev": true,
 			"requires": {
 				"ansi-escapes": "3.0.0",
@ -1699,7 +1699,7 @@
 				"ansi-styles": {
 					"version": "3.2.0",
 					"resolved": "https://registry.npmjs.org/ansi-styles/-/ansi-styles-3.2.0.tgz",
-					"integrity": "sha512-NnSOmMEYtVR2JVMIGTzynRkkaxtiq1xnFBcdQD/DnNCYPoEPsVJhM98BDyaoNOQIi7p4okdi3E27eN7GQbsUug==",
+					"integrity": "sha1-wVm41b4PnlpvNG2rlPFs4CIWG4g=",
 					"dev": true,
 					"requires": {
 						"color-convert": "1.9.1"
@ -2123,7 +2123,7 @@
 		"lru-cache": {
 			"version": "4.1.1",
 			"resolved": "https://registry.npmjs.org/lru-cache/-/lru-cache-4.1.1.tgz",
-			"integrity": "sha512-q4spe4KTfsAS1SUHLO0wz8Qiyf1+vMIAgpRYioFYDMNqKfHQbg+AVDH3i4fvpl71/P1L0dBl+fQi+P37UYf0ew==",
+			"integrity": "sha1-Yi4y6CSItJJ5EUpPns9F581rulU=",
 			"dev": true,
 			"requires": {
 				"pseudomap": "1.0.2",
@ -2218,7 +2218,7 @@
 		"minimatch": {
 			"version": "3.0.4",
 			"resolved": "https://registry.npmjs.org/minimatch/-/minimatch-3.0.4.tgz",
-			"integrity": "sha512-yJHVQEhyqPLUTgt9B83PXu6W3rx4MvvHvSUvToogpwoGDOUQ+yDrR0HRot+yOCdCO7u4hX3pWft6kWBBcqh0UA==",
+			"integrity": "sha1-UWbihkV/AzBgZL5Ul+jbsMPTIIM=",
 			"dev": true,
 			"requires": {
 				"brace-expansion": "1.1.8"
@ -2320,7 +2320,7 @@
 		"normalize-package-data": {
 			"version": "2.4.0",
 			"resolved": "https://registry.npmjs.org/normalize-package-data/-/normalize-package-data-2.4.0.tgz",
-			"integrity": "sha512-9jjUFbTPfEy3R/ad/2oNbKtW9Hgovl5O1FvFWKkKblNXoN/Oou6+9+KKohPK13Yc3/TyunyWhJp6gvRNR/PPAw==",
+			"integrity": "sha1-EvlaMH1YNSB1oEkHuErIvpisAS8=",
 			"dev": true,
 			"requires": {
 				"hosted-git-info": "2.5.0",
@ -2548,13 +2548,13 @@
 		"pluralize": {
 			"version": "7.0.0",
 			"resolved": "https://registry.npmjs.org/pluralize/-/pluralize-7.0.0.tgz",
-			"integrity": "sha512-ARhBOdzS3e41FbkW/XWrTEtukqqLoK5+Z/4UeDaLuSW+39JPeFgs4gCGqsrJHVZX0fUrx//4OF0K1CUGwlIFow==",
+			"integrity": "sha1-KYuJ34uTsCIdv0Ia0rGx6iP8Z3c=",
 			"dev": true
 		},
 		"postcss": {
 			"version": "5.2.18",
 			"resolved": "https://registry.npmjs.org/postcss/-/postcss-5.2.18.tgz",
-			"integrity": "sha512-zrUjRRe1bpXKsX1qAJNJjqZViErVuyEkMTRrwu4ud4sbTtIBRmtaYDrHmcGgmrbsW3MHfmtIf+vJumgQn+PrXg==",
+			"integrity": "sha1-ut+hSX1GJE9jkPWLMZgw2RB4U8U=",
 			"dev": true,
 			"requires": {
 				"chalk": "1.1.3",
@ -2691,7 +2691,7 @@
 		"randomatic": {
 			"version": "1.1.7",
 			"resolved": "https://registry.npmjs.org/randomatic/-/randomatic-1.1.7.tgz",
-			"integrity": "sha512-D5JUjPyJbaJDkuAazpVnSfVkLlpeO3wDlPROTMLGKG1zMFNFRgrciKo1ltz/AzNTkqE0HzDx655QOL51N06how==",
+			"integrity": "sha1-x6vpzIuHwLqodrGf3oP9RkeX44w=",
 			"dev": true,
 			"requires": {
 				"is-number": "3.0.0",
@ -2787,7 +2787,7 @@
 		"readable-stream": {
 			"version": "2.3.3",
 			"resolved": "https://registry.npmjs.org/readable-stream/-/readable-stream-2.3.3.tgz",
-			"integrity": "sha512-m+qzzcn7KUxEmd1gMbchF+Y2eIUbieUaxkWtptyHywrX0rE8QEYqPC07Vuy4Wm32/xE16NcdBctb8S0Xe/5IeQ==",
+			"integrity": "sha1-No8lEtefnUb9/HE0mueHi7weuVw=",
 			"dev": true,
 			"requires": {
 				"core-util-is": "1.0.2",
@ -2812,7 +2812,7 @@
 		"regex-cache": {
 			"version": "0.4.4",
 			"resolved": "https://registry.npmjs.org/regex-cache/-/regex-cache-0.4.4.tgz",
-			"integrity": "sha512-nVIZwtCjkC9YgvWkpM55B5rBhBYRZhAaJbgcFYXXsHnbZ9UZI9nnVWYZpBlCqv9ho2eZryPnWrZGsOdPwVWXWQ==",
+			"integrity": "sha1-db3FiioUls7EihKDW8VMjVYjNt0=",
 			"dev": true,
 			"requires": {
 				"is-equal-shallow": "0.1.3"
@ -2931,13 +2931,13 @@
 		"safe-buffer": {
 			"version": "5.1.1",
 			"resolved": "https://registry.npmjs.org/safe-buffer/-/safe-buffer-5.1.1.tgz",
-			"integrity": "sha512-kKvNJn6Mm93gAczWVJg7wH+wGYWNrDHdWvpUmHyEsgCtIwwo3bqPtV4tR5tuPaUhTOo/kvhVwd8XwwOllGYkbg==",
+			"integrity": "sha1-iTMSr2myEj3vcfV4iQAWce6yyFM=",
 			"dev": true
 		},
 		"sax": {
 			"version": "1.2.4",
 			"resolved": "https://registry.npmjs.org/sax/-/sax-1.2.4.tgz",
-			"integrity": "sha512-NqVDv9TpANUjFm0N8uM5GxL36UgKi9/atZw+x7YFnQ8ckwFGKrl4xX4yWtrey3UJm5nP1kUbnYgLopqWNSRhWw=="
+			"integrity": "sha1-KBYjTiN4vdxOU1T6tcqold9xANk="
 		},
 		"semver": {
 			"version": "5.5.0",
@ -2969,7 +2969,7 @@
 		"slice-ansi": {
 			"version": "1.0.0",
 			"resolved": "https://registry.npmjs.org/slice-ansi/-/slice-ansi-1.0.0.tgz",
-			"integrity": "sha512-POqxBK6Lb3q6s047D/XsDVNPnF9Dl8JSaqe9h9lURl0OdNqy/ujDrOiIHtsqXMGbWWTIomRzAMaTyawAU//Reg==",
+			"integrity": "sha1-BE8aSdiEL/MHqta1Be0Xi9lQE00=",
 			"dev": true,
 			"requires": {
 				"is-fullwidth-code-point": "2.0.0"
@ -3004,7 +3004,7 @@
 		"specificity": {
 			"version": "0.3.2",
 			"resolved": "https://registry.npmjs.org/specificity/-/specificity-0.3.2.tgz",
-			"integrity": "sha512-Nc/QN/A425Qog7j9aHmwOrlwX2e7pNI47ciwxwy4jOlvbbMHkNNJchit+FX+UjF3IAdiaaV5BKeWuDUnws6G1A==",
+			"integrity": "sha1-meZRHs7vD42bV5JJN6rCyxPRPEI=",
 			"dev": true
 		},
 		"split2": {
@ -3046,7 +3046,7 @@
 		"string-width": {
 			"version": "2.1.1",
 			"resolved": "https://registry.npmjs.org/string-width/-/string-width-2.1.1.tgz",
-			"integrity": "sha512-nOqH59deCq9SRHlxq1Aw85Jnt4w6KvLKqWVik6oA9ZklXLNIOlqg4F2yrT1MVaTjAqvVwdfeZ7w7aCvJD7ugkw==",
+			"integrity": "sha1-q5Pyeo3BPSjKyBXEYhQ6bZASrp4=",
 			"dev": true,
 			"requires": {
 				"is-fullwidth-code-point": "2.0.0",
@ -3073,7 +3073,7 @@
 		"string_decoder": {
 			"version": "1.0.3",
 			"resolved": "https://registry.npmjs.org/string_decoder/-/string_decoder-1.0.3.tgz",
-			"integrity": "sha512-4AH6Z5fzNNBcH+6XDMfA/BTt87skxqJlO0lAh3Dker5zThcAxG6mKz+iGu308UKoPPQ8Dcqx/4JhujzltRa+hQ==",
+			"integrity": "sha1-D8Z9fBQYJd6UKC3VNr7GubzoYKs=",
 			"dev": true,
 			"requires": {
 				"safe-buffer": "5.1.1"
@ -3294,7 +3294,7 @@
 		"table": {
 			"version": "4.0.2",
 			"resolved": "https://registry.npmjs.org/table/-/table-4.0.2.tgz",
-			"integrity": "sha512-UUkEAPdSGxtRpiV9ozJ5cMTtYiqz7Ni1OGqLXRCynrvzdtR1p+cfOWe2RJLwvUG8hNanaSRjecIqwOjqeatDsA==",
+			"integrity": "sha1-ozRHN1OR52atNNNIbm4q7chNLjY=",
 			"dev": true,
 			"requires": {
 				"ajv": "5.5.2",
@ -3308,7 +3308,7 @@
 				"ansi-styles": {
 					"version": "3.2.0",
 					"resolved": "https://registry.npmjs.org/ansi-styles/-/ansi-styles-3.2.0.tgz",
-					"integrity": "sha512-NnSOmMEYtVR2JVMIGTzynRkkaxtiq1xnFBcdQD/DnNCYPoEPsVJhM98BDyaoNOQIi7p4okdi3E27eN7GQbsUug==",
+					"integrity": "sha1-wVm41b4PnlpvNG2rlPFs4CIWG4g=",
 					"dev": true,
 					"requires": {
 						"color-convert": "1.9.1"
@ -3412,7 +3412,7 @@
 		"tmp": {
 			"version": "0.0.33",
 			"resolved": "https://registry.npmjs.org/tmp/-/tmp-0.0.33.tgz",
-			"integrity": "sha512-jRCJlojKnZ3addtTOjdIqoRuPEKBvNXcGYqzO6zWZX8KfKEpnGY5jfggJQ3EjKuu8D4bJRr0y+cYJFmYbImXGw==",
+			"integrity": "sha1-bTQzWIl2jSGyvNoKonfO07G/rfk=",
 			"dev": true,
 			"requires": {
 				"os-tmpdir": "1.0.2"
--- a/package.json
+++ b/package.json
@ -2,7 +2,7 @@
 	"private": true,
 	"scripts": {
 		"test": "grunt test && npm run doc && dev-scripts/svg_check.sh",
-		"doc": "jsduck"
+		"doc": "jsdoc -c jsdoc.json"
 	},
 	"dependencies": {
 		"jsdoc": "3.5.5",
--- a/resources/skins.minerva.backtotop/BackToTopOverlay.js
+++ b/resources/skins.minerva.backtotop/BackToTopOverlay.js
@ -6,6 +6,7 @@
 	 * Displays a little arrow at the bottom right of the viewport.
 	 * @class BackToTopOverlay
 	 * @extends View
+	 * @module skins.minerva.backtotop/BackToTopOverlay
 	 */
 	function BackToTopOverlay() {
 		View.apply( this, arguments );
--- a/resources/skins.minerva.mainMenu/MainMenu.js
+++ b/resources/skins.minerva.mainMenu/MainMenu.js
@ -7,9 +7,9 @@
 	 *
 	 * @class MainMenu
 	 * @extends View
-	 *
 	 * @constructor
 	 * @param {Object} options Configuration options
+	 * @module skins.minerva.mainMenu/MainMenu
 	 */
 	function MainMenu( options ) {
 		this.activator = options.activator;
@ -104,6 +104,7 @@
 		 * Toggle open navigation drawer
 		 * @param {string} [drawerType] A name that identifies the navigation drawer that
 		 *     should be toggled open. Defaults to 'primary'.
+		 * @fires MainMenu#open
 		 */
 		openNavigationDrawer: function ( drawerType ) {
 			// close any existing ones first.
@ -112,9 +113,7 @@
 			// FIXME: We should be moving away from applying classes to the body
 			$( 'body' ).toggleClass( 'navigation-enabled' )
 				.toggleClass( drawerType + '-navigation-enabled' );
-			/**
-			 * @event open emitted when navigation drawer is opened
-			 */
+
 			this.emit( 'open' );
 		}
 	} );
--- a/resources/skins.minerva.newusers/PointerOverlay.js
+++ b/resources/skins.minerva.newusers/PointerOverlay.js
@ -6,6 +6,7 @@
 	/**
 	 * Page overlay prompting a user for given action
 	 * @class PointerOverlay
+	 * @module skins.minerva.newusers/PointerOverlay
 	 */
 	function PointerOverlay() {
 		Overlay.apply( this, arguments );
--- a/resources/skins.minerva.notifications.badge/NotificationBadge.js
+++ b/resources/skins.minerva.notifications.badge/NotificationBadge.js
@ -14,6 +14,7 @@
 	 *
 	 * @constructor
 	 * @param {Object} options Configuration options
+	 * @module skins.minerva.notifications/NotificationBadge
 	 */
 	function NotificationBadge( options ) {
 		var $el,
--- a/resources/skins.minerva.scripts/DownloadIcon.js
+++ b/resources/skins.minerva.scripts/DownloadIcon.js
@ -36,6 +36,7 @@
 	 * @param {Number[]} [supportedNamespaces]
 	 * @param {Window} [windowObj] window object
 	 * @constructor
+	 * @module skins.minerva.scripts/DownloadIcon
 	 */
 	function DownloadIcon( skin, supportedNamespaces, windowObj ) {
 		var options = {};