Merge branch 'winh-jsdoc' into 'master'

Generate searchable JSDoc documentation

See merge request gitlab-org/gitlab-ce!23583

.gitignore

@@ -80,3 +80,4 @@ eslint-report.html
 package-lock.json
 /junit_*.xml
 /coverage-frontend/
+jsdoc/

.gitlab-ci.yml

@@ -850,6 +850,21 @@ lint:javascript:report:
     paths:
       - eslint-report.html
 
+jsdoc:
+  <<: *dedicated-no-docs-pull-cache-job
+  stage: post-test
+  dependencies:
+    - compile-assets
+  before_script: []
+  script:
+    - date
+    - yarn run jsdoc || true # ignore exit code
+  artifacts:
+    name: jsdoc
+    expire_in: 31d
+    paths:
+      - jsdoc/
+
 pages:
   <<: *dedicated-no-docs-no-db-pull-cache-job
   before_script: []
@@ -859,6 +874,7 @@ pages:
     - karma
     - gitlab:assets:compile
     - lint:javascript:report
+    - jsdoc
   script:
     - mv public/ .public/
     - mkdir public/
@@ -868,6 +884,7 @@ pages:
     - mv webpack-report/ public/webpack-report/ || true
     - cp .public/assets/application-*.css public/application.css || true
     - cp .public/assets/application-*.css.gz public/application.css.gz || true
+    - mv jsdoc/ public/jsdoc/ || true
   artifacts:
     paths:
       - public

app/assets/javascripts/ide/index.js

@@ -9,6 +9,13 @@ import { parseBoolean } from '../lib/utils/common_utils';
 
 Vue.use(Translate);
 
+/**
+ * Function that receives the default store and returns an extended one.
+ * @callback extendStoreCallback
+ * @param {Vuex.Store} store
+ * @param {Element} el
+ */
+
 /**
  * Initialize the IDE on the given element.
  *
@@ -16,7 +23,7 @@ Vue.use(Translate);
  * @param {Object} options - Extra options for the IDE (Used by EE).
  * @param {Component} options.rootComponent -
  *   Component that overrides the root component.
- * @param {(store:Vuex.Store, el:Element) => Vuex.Store} options.extendStore -
+ * @param {extendStoreCallback} options.extendStore -
  *   Function that receives the default store and returns an extended one.
  */
 export function initIde(el, options = {}) {

app/assets/javascripts/lib/utils/common_utils.js

+/**
+ * @module common-utils
+ */
+
 import $ from 'jquery';
 import axios from './axios_utils';
 import { getLocationHash } from './url_utility';
@@ -449,11 +453,17 @@ export const convertPermissionToBoolean = permission => {
   return parseBoolean(permission);
 };
 
+/**
+ * @callback backOffCallback
+ * @param {Function} next
+ * @param {Function} stop
+ */
+
 /**
  * Back Off exponential algorithm
  * backOff :: (Function<next, stop>, Number) -> Promise<Any, Error>
  *
- * @param {Function<next, stop>} fn function to be called
+ * @param {backOffCallback} fn function to be called
  * @param {Number} timeout
  * @return {Promise<Any, Error>}
  * @example

app/assets/javascripts/locale/sprintf.js

@@ -4,8 +4,8 @@ import _ from 'underscore';
   Very limited implementation of sprintf supporting only named parameters.
 
   @param input (translated) text with parameters (e.g. '%{num_users} users use us')
-  @param parameters object mapping parameter names to values (e.g. { num_users: 5 })
-  @param escapeParameters whether parameter values should be escaped (see http://underscorejs.org/#escape)
+  @param {Object} parameters object mapping parameter names to values (e.g. { num_users: 5 })
+  @param {Boolean} escapeParameters whether parameter values should be escaped (see http://underscorejs.org/#escape)
   @returns {String} the text with parameters replaces (e.g. '5 users use us')
 
   @see https://ruby-doc.org/core-2.3.3/Kernel.html#method-i-sprintf

config/jsdocs.config.js

+module.exports = {
+  source: {
+    include: ['app/assets/javascripts/'],
+  },
+  opts: {
+    template: 'node_modules/docdash',
+    destination: 'jsdoc/',
+    recurse: true,
+  },
+  docdash: {
+    search: true,
+    static: true,
+  },
+};

package.json

@@ -7,6 +7,7 @@
     "eslint-fix": "eslint --max-warnings 0 --report-unused-disable-directives --ext .js,.vue --fix .",
     "eslint-report": "eslint --max-warnings 0 --ext .js,.vue --format html --output-file ./eslint-report.html --no-inline-config .",
     "jest": "BABEL_ENV=jest jest",
+    "jsdoc": "jsdoc -c config/jsdocs.config.js",
     "karma": "BABEL_ENV=${BABEL_ENV:=karma} karma start --single-run true config/karma.config.js",
     "karma-coverage": "BABEL_ENV=coverage karma start --single-run true config/karma.config.js",
     "karma-start": "BABEL_ENV=karma karma start config/karma.config.js",
@@ -132,6 +133,7 @@
     "babel-types": "^6.26.0",
     "chalk": "^2.4.1",
     "commander": "^2.18.0",
+    "docdash": "^1.0.2",
     "eslint": "~5.9.0",
     "eslint-import-resolver-jest": "^2.1.1",
     "eslint-import-resolver-webpack": "^0.10.1",
@@ -148,6 +150,8 @@
     "jasmine-jquery": "^2.1.1",
     "jest": "^23.6.0",
     "jest-junit": "^5.2.0",
+    "jsdoc": "^3.5.5",
+    "jsdoc-vue": "^1.0.0",
     "karma": "^3.0.0",
     "karma-chrome-launcher": "^2.2.0",
     "karma-coverage-istanbul-reporter": "^2.0.4",