[gjs: 37/43] CI: Add valid-jsdoc to eslint rules

[Philip Chimento <pchimento src gnome org>]

commit 2ff50b5c1e8433d61fd9b22ef0c08bbaa069b0fc
Author: Philip Chimento <philip chimento gmail com>
Date:   Sun Aug 4 11:51:23 2019 -0700

    CI: Add valid-jsdoc to eslint rules
    
    We don't really use jsdoc, but it's planned, as we really need to be
    able to document the overrides! So if we do have jsdoc comments, then
    they should be valid.

 .eslintrc.yml                |  3 +++
 modules/_legacy.js           |  3 +--
 modules/gettext.js           |  5 ++---
 modules/lang.js              |  5 ++---
 modules/package.js           | 39 +++++++++++++++++----------------------
 modules/tweener/equations.js |  2 +-
 6 files changed, 26 insertions(+), 31 deletions(-)
---
diff --git a/.eslintrc.yml b/.eslintrc.yml
index 6bfbe8da..c912866a 100644
--- a/.eslintrc.yml
+++ b/.eslintrc.yml
@@ -141,6 +141,9 @@ rules:
     - int32Hint: false
   space-unary-ops: error
   spaced-comment: error
+  valid-jsdoc:
+    - error
+    - requireReturn: false
 globals:
   ARGV: readonly
   Debugger: readonly
diff --git a/modules/_legacy.js b/modules/_legacy.js
index 40d64b89..86970fac 100644
--- a/modules/_legacy.js
+++ b/modules/_legacy.js
@@ -162,8 +162,7 @@ Class.prototype._construct = function (params, ...otherArgs) {
 /**
  * Check whether this class conforms to the interface "iface".
  * @param {object} iface a Lang.Interface
- * @returns: whether this class implements iface
- * @type: boolean
+ * @returns {boolean} whether this class implements iface
  */
 Class.prototype.implements = function (iface) {
     if (_interfacePresent(iface, this.prototype))
diff --git a/modules/gettext.js b/modules/gettext.js
index 8bc06d4a..3c43ff94 100644
--- a/modules/gettext.js
+++ b/modules/gettext.js
@@ -80,9 +80,8 @@ function dpgettext(dom, context, msgid) {
  * Create an object with bindings for gettext, ngettext,
  * and pgettext bound to a particular translation domain.
  *
- * @param domainName Translation domain string
- * @returns: an object with gettext bindings
- * @type: function
+ * @param {string} domainName Translation domain string
+ * @returns {object} an object with gettext bindings
  */
 function domain(domainName) {
     return {
diff --git a/modules/lang.js b/modules/lang.js
index 9986f03c..c40f66d4 100644
--- a/modules/lang.js
+++ b/modules/lang.js
@@ -62,9 +62,8 @@ function copyPublicProperties(source, dest) {
  * using this within the callback.
  * @param {object} obj the object to bind
  * @param {function} callback callback to bind obj in
- * @param arguments additional arguments to the callback
- * @returns: a new callback
- * @type: function
+ * @param {*} bindArguments additional arguments to the callback
+ * @returns {function} a new callback
  */
 function bind(obj, callback, ...bindArguments) {
     if (typeof obj !== 'object') {
diff --git a/modules/package.js b/modules/package.js
index 71d7011a..e3c3d186 100644
--- a/modules/package.js
+++ b/modules/package.js
@@ -75,12 +75,9 @@ function _makeNamePath(n) {
 }
 
 /**
- * init:
- * @params: package parameters
- *
  * Initialize directories and global variables. Must be called
  * before any of other API in Package is used.
- * @params must be an object with at least the following keys:
+ * `params` must be an object with at least the following keys:
  *  - name: the package name ($(PACKAGE_NAME) in autotools,
  *          eg. org.foo.Bar)
  *  - version: the package version
@@ -116,6 +113,8 @@ function _makeNamePath(n) {
  * All paths are absolute and will not end with '/'.
  *
  * As a side effect, init() calls GLib.set_prgname().
+ *
+ * @param {object} params package parameters
  */
 function init(params) {
     window.pkg = imports.package;
@@ -196,13 +195,11 @@ function init(params) {
 }
 
 /**
- * start:
- * @params: see init()
- *
  * This is a convenience function if your package has a
  * single entry point.
  * You must define a main(ARGV) function inside a main.js
  * module in moduledir.
+ * @param {object} params see init()
  */
 function start(params) {
     init(params);
@@ -210,9 +207,6 @@ function start(params) {
 }
 
 /**
- * run:
- * @module: the module to run
- *
  * This is the function to use if you want to have multiple
  * entry points in one package.
  * You must define a main(ARGV) function inside the passed
@@ -220,20 +214,21 @@ function start(params) {
  *
  * imports.package.init(...);
  * imports.package.run(imports.entrypoint);
+ *
+ * @param {object} module the module to run
+ * @returns {number|undefined} the exit code of the module's main() function
  */
 function run(module) {
     return module.main([System.programInvocationName].concat(ARGV));
 }
 
 /**
- * require:
- * @libs: the external dependencies to import
- *
  * Mark a dependency on a specific version of one or more
  * external GI typelibs.
- * @libs must be an object whose keys are a typelib name,
+ * `libs` must be an object whose keys are a typelib name,
  * and values are the respective version. The empty string
  * indicates any version.
+ * @param {object} libs the external dependencies to import
  */
 function require(libs) {
     for (let l in libs)
@@ -241,10 +236,11 @@ function require(libs) {
 }
 
 /**
- * requireSymbol:
- *
  * As checkSymbol(), but exit with an error if the
  * dependency cannot be satisfied.
+ * @param {string} lib an external dependency to import
+ * @param {string} [ver] version of the dependency
+ * @param {string} [symbol] symbol to check for
  */
 function requireSymbol(lib, ver, symbol) {
     if (!checkSymbol(lib, ver, symbol)) {
@@ -257,11 +253,6 @@ function requireSymbol(lib, ver, symbol) {
 }
 
 /**
- * checkSymbol:
- * @lib: an external dependency to import
- * @version: optional version of the dependency
- * @symbol: optional symbol to check for
- *
  * Check whether an external GI typelib can be imported
  * and provides @symbol.
  *
@@ -271,7 +262,11 @@ function requireSymbol(lib, ver, symbol) {
  *  - class / instance methods ('IconTheme.get_default' / 'IconTheme.has_icon')
  *  - GObject properties       ('Window.default_height')
  *
- * Returns: %true if @lib can be imported and provides @symbol, %false otherwise
+ * @param {string} lib an external dependency to import
+ * @param {string} [ver] version of the dependency
+ * @param {string} [symbol] symbol to check for
+ * @return {boolean} true if `lib` can be imported and provides `symbol`, false
+ * otherwise
  */
 function checkSymbol(lib, ver, symbol) {
     let Lib = null;
diff --git a/modules/tweener/equations.js b/modules/tweener/equations.js
index fdcbc745..7b478793 100644
--- a/modules/tweener/equations.js
+++ b/modules/tweener/equations.js
@@ -1,5 +1,5 @@
 /* -*- mode: js; js-indent-level: 4; indent-tabs-mode: nil; -*- */
-/* eslint-disable no-unused-vars */
+/* eslint-disable no-unused-vars, valid-jsdoc */
 
 /* Copyright 2008 litl, LLC. */
 /**