js: Add JSDoc to exported functions and fix incorrect JSDoc formatting

Part-of: <https://gitlab.gnome.org/GNOME/gnome-shell/-/merge_requests/1499>

js/misc/config.js.in

@@ -15,7 +15,7 @@ var LOCALEDIR = '@datadir@/locale';
 var LIBEXECDIR = '@libexecdir@';
 var PKGDATADIR = '@datadir@/@PACKAGE_NAME@';
 /* g-i package versions */
-var LIBMUTTER_API_VERSION = '@LIBMUTTER_API_VERSION@'
+var LIBMUTTER_API_VERSION = '@LIBMUTTER_API_VERSION@';
 
 var HAVE_BLUETOOTH = pkg.checkSymbol('GnomeBluetooth', '3.0',
     'Client.default_adapter_state')

js/misc/extensionUtils.js

@@ -12,6 +12,9 @@ var ExtensionType = {
     PER_USER: 2,
 };
 
+/**
+ * @enum {number}
+ */
 var ExtensionState = {
     ENABLED: 1,
     DISABLED: 2,

js/misc/fileUtils.js

@@ -44,6 +44,10 @@ function* collectFromDatadirs(subdir, includeUserDir) {
     }
 }
 
+/**
+ * @param {Gio.File} dir
+ * @param {boolean} deleteParent
+ */
 function recursivelyDeleteDir(dir, deleteParent) {
     let children = dir.enumerate_children('standard::name,standard::type',
         Gio.FileQueryInfoFlags.NOFOLLOW_SYMLINKS, null);
@@ -62,6 +66,10 @@ function recursivelyDeleteDir(dir, deleteParent) {
         dir.delete(null);
 }
 
+/**
+ * @param {Gio.File} srcDir
+ * @param {Gio.File} destDir
+ */
 function recursivelyMoveDir(srcDir, destDir) {
     let children = srcDir.enumerate_children('standard::name,standard::type',
         Gio.FileQueryInfoFlags.NOFOLLOW_SYMLINKS, null);

js/misc/gnomeSession.js

@@ -7,6 +7,7 @@ const { loadInterfaceXML } = imports.misc.fileUtils;
 
 const PresenceIface = loadInterfaceXML('org.gnome.SessionManager.Presence');
 
+/** @enum {number} */
 var PresenceStatus = {
     AVAILABLE: 0,
     INVISIBLE: 1,
@@ -15,6 +16,12 @@ var PresenceStatus = {
 };
 
 var PresenceProxy = Gio.DBusProxy.makeProxyWrapper(PresenceIface);
+
+/**
+ * @param {Function} initCallback
+ * @param {Gio.Cancellable} cancellable
+ * @returns {Gio.DBusProxy}
+ */
 function Presence(initCallback, cancellable) {
     return new PresenceProxy(Gio.DBus.session, 'org.gnome.SessionManager',
                              '/org/gnome/SessionManager/Presence', initCallback, cancellable);
@@ -25,6 +32,13 @@ function Presence(initCallback, cancellable) {
 // of new inhibitors)
 const InhibitorIface = loadInterfaceXML('org.gnome.SessionManager.Inhibitor');
 var InhibitorProxy = Gio.DBusProxy.makeProxyWrapper(InhibitorIface);
+
+/**
+ * @param {string} objectPath
+ * @param {Function} initCallback
+ * @param {Gio.Cancellable} cancellable
+ * @returns {Gio.DBusProxy}
+ */
 function Inhibitor(objectPath, initCallback, cancellable) {
     return new InhibitorProxy(Gio.DBus.session, 'org.gnome.SessionManager', objectPath, initCallback, cancellable);
 }
@@ -32,6 +46,12 @@ function Inhibitor(objectPath, initCallback, cancellable) {
 // Not the full interface, only the methods we use
 const SessionManagerIface = loadInterfaceXML('org.gnome.SessionManager');
 var SessionManagerProxy = Gio.DBusProxy.makeProxyWrapper(SessionManagerIface);
+
+/**
+ * @param {Function} initCallback
+ * @param {Gio.Cancellable} cancellable
+ * @returns {Gio.DBusProxy}
+ */
 function SessionManager(initCallback, cancellable) {
     return new SessionManagerProxy(Gio.DBus.session, 'org.gnome.SessionManager', '/org/gnome/SessionManager', initCallback, cancellable);
 }

js/misc/ibusManager.js

@@ -46,6 +46,9 @@ function _checkIBusVersion(requiredMajor, requiredMinor, requiredMicro) {
         `but required is ${requiredMajor}.${requiredMinor}.${requiredMicro}`);
 }
 
+/**
+ * @returns {IBusManager}
+ */
 function getIBusManager() {
     if (_ibusManager == null)
         _ibusManager = new IBusManager();

js/misc/keyboardManager.js

@@ -12,6 +12,9 @@ var DEFAULT_VARIANT = '';
 
 let _xkbInfo = null;
 
+/**
+ * @returns {GnomeDesktop.XkbInfo}
+ */
 function getXkbInfo() {
     if (_xkbInfo == null)
         _xkbInfo = new GnomeDesktop.XkbInfo();
@@ -20,6 +23,9 @@ function getXkbInfo() {
 
 let _keyboardManager = null;
 
+/**
+ * @returns {KeyboardManager}
+ */
 function getKeyboardManager() {
     if (_keyboardManager == null)
         _keyboardManager = new KeyboardManager();

js/misc/loginManager.js

@@ -33,6 +33,9 @@ function versionCompare(required, reference) {
     return true;
 }
 
+/**
+ * @returns {boolean}
+ */
 function canLock() {
     try {
         let params = GLib.Variant.new('(ss)', ['org.gnome.DisplayManager.Manager', 'Version']);
@@ -74,8 +77,7 @@ let _loginManager = null;
 /**
  * getLoginManager:
  * An abstraction over systemd/logind and ConsoleKit.
- * @returns {object} - the LoginManager singleton
- *
+ * @returns {LoginManagerSystemd | LoginManagerDummy} - the LoginManager singleton
  */
 function getLoginManager() {
     if (_loginManager == null) {

js/misc/params.js

@@ -1,20 +1,23 @@
 // -*- mode: js; js-indent-level: 4; indent-tabs-mode: nil -*-
 /* exported parse */
 
-// parse:
-// @params: caller-provided parameter object, or %null
-// @defaults-provided defaults object
-// @allowExtras: whether or not to allow properties not in @default
-//
-// Examines @params and fills in default values from @defaults for
-// any properties in @defaults that don't appear in @params. If
-// @allowExtras is not %true, it will throw an error if @params
-// contains any properties that aren't in @defaults.
-//
-// If @params is %null, this returns the values from @defaults.
-//
-// Return value: a new object, containing the merged parameters from
-// @params and @defaults
+/**
+ * parse:
+ *
+ * @param {*} params caller-provided parameter object, or %null
+ * @param {*} defaults provided defaults object
+ * @param {boolean} [allowExtras] whether or not to allow properties not in `default`
+ *
+ * @summary Examines `params` and fills in default values from `defaults` for
+ * any properties in `default` that don't appear in `params`. If
+ * `allowExtras` is not %true, it will throw an error if `params`
+ * contains any properties that aren't in `defaults`.
+ *
+ * If `params` is %null, this returns the values from `defaults`.
+ *
+ * @returns a new object, containing the merged parameters from
+ * `params` and `defaults`
+ */
 function parse(params = {}, defaults, allowExtras) {
     if (!allowExtras) {
         for (let prop in params) {

js/misc/parentalControlsManager.js

@@ -39,6 +39,9 @@ if (HAVE_MALCONTENT) {
 
 let _singleton = null;
 
+/**
+ * @returns {ParentalControlsManager}
+ */
 function getDefault() {
     if (_singleton === null)
         _singleton = new ParentalControlsManager();

js/misc/permissionStore.js

@@ -8,6 +8,11 @@ const { loadInterfaceXML } = imports.misc.fileUtils;
 const PermissionStoreIface = loadInterfaceXML('org.freedesktop.impl.portal.PermissionStore');
 const PermissionStoreProxy = Gio.DBusProxy.makeProxyWrapper(PermissionStoreIface);
 
+/**
+ * @param {Function} initCallback
+ * @param {Gio.Cancellable} cancellable
+ * @returns {Gio.DBusProxy}
+ */
 function PermissionStore(initCallback, cancellable) {
     return new PermissionStoreProxy(Gio.DBus.session,
                                     'org.freedesktop.impl.portal.PermissionStore',

js/misc/smartcardManager.js

@@ -18,6 +18,9 @@ const SmartcardTokenIface = `
 
 let _smartcardManager = null;
 
+/**
+ * @returns {SmartcardManager}
+ */
 function getSmartcardManager() {
     if (_smartcardManager == null)
         _smartcardManager = new SmartcardManager();

js/misc/systemActions.js

@@ -30,6 +30,9 @@ const SCREENSHOT_UI_ACTION_ID    = 'open-screenshot-ui';
 
 let _singleton = null;
 
+/**
+ * @returns {SystemActions}
+ */
 function getDefault() {
     if (_singleton == null)
         _singleton = new SystemActions();

js/misc/util.js

@@ -41,14 +41,17 @@ const _urlRegexp = new RegExp(
 
 let _desktopSettings = null;
 
-// findUrls:
-// @str: string to find URLs in
-//
-// Searches @str for URLs and returns an array of objects with %url
-// properties showing the matched URL string, and %pos properties indicating
-// the position within @str where the URL was found.
-//
-// Return value: the list of match objects, as described above
+/**
+ * findUrls:
+ *
+ * @param {string} str string to find URLs in
+ *
+ * Searches `str` for URLs and returns an array of objects with %url
+ * properties showing the matched URL string, and %pos properties indicating
+ * the position within `str` where the URL was found.
+ *
+ * @returns {{url: string, pos: number}[]} the list of match objects, as described above
+ */
 function findUrls(str) {
     let res = [], match;
     while ((match = _urlRegexp.exec(str)))
@@ -56,11 +59,14 @@ function findUrls(str) {
     return res;
 }
 
-// spawn:
-// @argv: an argv array
-//
-// Runs @argv in the background, handling any errors that occur
-// when trying to start the program.
+/**
+ * spawn:
+ *
+ * Runs `argv` in the background, handling any errors that occur
+ * when trying to start the program.
+ *
+ * @param {readonly string[]} argv an argv array
+ */
 function spawn(argv) {
     try {
         trySpawn(argv);
@@ -69,11 +75,14 @@ function spawn(argv) {
     }
 }
 
-// spawnCommandLine:
-// @commandLine: a command line
-//
-// Runs @commandLine in the background, handling any errors that
-// occur when trying to parse or start the program.
+/**
+ * spawnCommandLine:
+ *
+ * @param {readonly string[]} commandLine a command line
+ *
+ * Runs commandLine in the background, handling any errors that
+ * occur when trying to parse or start the program.
+ */
 function spawnCommandLine(commandLine) {
     try {
         let [success_, argv] = GLib.shell_parse_argv(commandLine);
@@ -83,10 +92,13 @@ function spawnCommandLine(commandLine) {
     }
 }
 
-// spawnApp:
-// @argv: an argv array
-//
-// Runs @argv as if it was an application, handling startup notification
+/**
+ * spawnApp:
+ *
+ * @param {readonly string[]} argv an argv array
+ *
+ * Runs argv as if it was an application, handling startup notification
+ */
 function spawnApp(argv) {
     try {
         let app = Gio.AppInfo.create_from_commandline(argv.join(' '), null,
@@ -99,13 +111,16 @@ function spawnApp(argv) {
     }
 }
 
-// trySpawn:
-// @argv: an argv array
-//
-// Runs @argv in the background. If launching @argv fails,
-// this will throw an error.
+/**
+ * trySpawn:
+ *
+ * @param {readonly string[]} argv an argv array
+ *
+ * Runs argv in the background. If launching argv fails,
+ * this will throw an error.
+ */
 function trySpawn(argv) {
-    var success_, pid;
+    let success_, pid;
     try {
         [success_, pid] = GLib.spawn_async(
             null, argv, null,
@@ -146,11 +161,14 @@ function trySpawn(argv) {
     GLib.child_watch_add(GLib.PRIORITY_DEFAULT, pid, () => {});
 }
 
-// trySpawnCommandLine:
-// @commandLine: a command line
-//
-// Runs @commandLine in the background. If launching @commandLine
-// fails, this will throw an error.
+/**
+ * trySpawnCommandLine:
+ *
+ * @param {readonly string[]} commandLine a command line
+ *
+ * Runs commandLine in the background. If launching commandLine
+ * fails, this will throw an error.
+ */
 function trySpawnCommandLine(commandLine) {
     let success_, argv;
 
@@ -171,6 +189,14 @@ function _handleSpawnError(command, err) {
     Main.notifyError(title, err.message);
 }
 
+/**
+ * Returns an {@link St.Label} with the date passed formatted
+ * using {@link formatTime}
+ *
+ * @param {Date} date the date to format for the label
+ * @param {object} params params for {@link formatTime}
+ * @returns {St.Label}
+ */
 function createTimeLabel(date, params) {
     if (_desktopSettings == null)
         _desktopSettings = new Gio.Settings({ schema_id: 'org.gnome.desktop.interface' });
@@ -182,20 +208,26 @@ function createTimeLabel(date, params) {
     return label;
 }
 
-// lowerBound:
-// @array: an array or array-like object, already sorted
-//         according to @cmp
-// @val: the value to add
-// @cmp: a comparator (or undefined to compare as numbers)
-//
-// Returns the position of the first element that is not
-// lower than @val, according to @cmp.
-// That is, returns the first position at which it
-// is possible to insert @val without violating the
-// order.
-// This is quite like an ordinary binary search, except
-// that it doesn't stop at first element comparing equal.
 
+/**
+ * lowerBound:
+ *
+ * @template T, [K=T]
+ * @param {readonly T[]} array an array or array-like object, already sorted
+ *         according to `cmp`
+ * @param {K} val the value to add
+ * @param {(a: T, val: K) => number} cmp a comparator (or undefined to compare as numbers)
+ * @returns {number}
+ *
+ * Returns the position of the first element that is not
+ * lower than `val`, according to `cmp`.
+ * That is, returns the first position at which it
+ * is possible to insert val without violating the
+ * order.
+ *
+ * This is quite like an ordinary binary search, except
+ * that it doesn't stop at first element comparing equal.
+ */
 function lowerBound(array, val, cmp) {
     let min, max, mid, v;
     cmp ||= (a, b) => a - b;
@@ -218,14 +250,20 @@ function lowerBound(array, val, cmp) {
     return min == max || cmp(array[min], val) < 0 ? max : min;
 }
 
-// insertSorted:
-// @array: an array sorted according to @cmp
-// @val: a value to insert
-// @cmp: the sorting function
-//
-// Inserts @val into @array, preserving the
-// sorting invariants.
-// Returns the position at which it was inserted
+/**
+ * insertSorted:
+ *
+ * @template T, [K=T]
+ * @param {T[]} array an array sorted according to `cmp`
+ * @param {K} val a value to insert
+ * @param {(a: T, val: K) => number} cmp the sorting function
+ * @returns {number}
+ *
+ * Inserts `val` into `array`, preserving the
+ * sorting invariants.
+ *
+ * Returns the position at which it was inserted
+ */
 function insertSorted(array, val, cmp) {
     let pos = lowerBound(array, val, cmp);
     array.splice(pos, 0, val);
@@ -233,15 +271,25 @@ function insertSorted(array, val, cmp) {
     return pos;
 }
 
+/**
+ * @param {number} start
+ * @param {number} end
+ * @param {number} progress
+ * @returns {number}
+ */
 function lerp(start, end, progress) {
     return start + progress * (end - start);
 }
 
-// _GNOMEversionToNumber:
-// @version: a GNOME version element
-//
-// Like Number() but returns sortable values for special-cases
-// 'alpha' and 'beta'. Returns NaN for unhandled 'versions'.
+/**
+ * _GNOMEversionToNumber:
+ *
+ * @param {string} version a GNOME version element
+ * @returns {number}
+ *
+ * Like Number() but returns sortable values for special-cases
+ * 'alpha' and 'beta'. Returns NaN for unhandled 'versions'.
+ */
 function _GNOMEversionToNumber(version) {
     let ret = Number(version);
     if (!isNaN(ret))
@@ -253,12 +301,16 @@ function _GNOMEversionToNumber(version) {
     return ret;
 }
 
-// GNOMEversionCompare:
-// @version1: a string containing a GNOME version
-// @version2: a string containing another GNOME version
-//
-// Returns an integer less than, equal to, or greater than
-// zero, if version1 is older, equal or newer than version2
+/**
+ * GNOMEversionCompare:
+ *
+ * @param {string} version1 a string containing a GNOME version
+ * @param {string} version2 a string containing another GNOME version
+ * @returns {number}
+ *
+ * Returns an integer less than, equal to, or greater than
+ * zero, if `version1` is older, equal or newer than `version2`
+ */
 function GNOMEversionCompare(version1, version2) {
     const v1Array = version1.split('.');
     const v2Array = version2.split('.');