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

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

js/gdm/authPrompt.js

@@ -23,11 +23,13 @@ var DEFAULT_BUTTON_WELL_ANIMATION_TIME = 300;
 
 var MESSAGE_FADE_OUT_ANIMATION_TIME = 500;
 
+/** @enum {number} */
 var AuthPromptMode = {
     UNLOCK_ONLY: 0,
     UNLOCK_OR_LOG_IN: 1,
 };
 
+/** @enum {number} */
 var AuthPromptStatus = {
     NOT_VERIFYING: 0,
     VERIFYING: 1,
@@ -37,6 +39,7 @@ var AuthPromptStatus = {
     VERIFICATION_IN_PROGRESS: 5,
 };
 
+/** @enum {number} */
 var BeginRequestType = {
     PROVIDE_USERNAME: 0,
     DONT_PROVIDE_USERNAME: 1,

js/gdm/oVirt.js

@@ -43,6 +43,9 @@ var OVirtCredentialsManager = class OVirtCredentialsManager extends Credential.C
     }
 };
 
+/**
+ * @returns {OVirtCredentialsManager}
+ */
 function getOVirtCredentialsManager() {
     if (!_oVirtCredentialsManager)
         _oVirtCredentialsManager = new OVirtCredentialsManager();

js/gdm/util.js

@@ -49,8 +49,12 @@ var DISABLE_USER_LIST_KEY = 'disable-user-list';
 var USER_READ_TIME = 48;
 const FINGERPRINT_ERROR_TIMEOUT_WAIT = 15;
 
+/**
+ * Keep messages in order by priority
+ *
+ * @enum {number}
+ */
 var MessageType = {
-    // Keep messages in order by priority
     NONE: 0,
     HINT: 1,
     INFO: 2,
@@ -109,6 +113,9 @@ function fadeOutActor(actor) {
     return hold;
 }
 
+/**
+ * @param {Clutter.Actor} actor
+ */
 function cloneAndFadeOutActor(actor) {
     // Immediately hide actor so its sibling can have its space
     // and position, but leave a non-reactive clone on-screen,

js/gdm/vmware.js

@@ -46,6 +46,9 @@ var VmwareCredentialsManager = class VmwareCredentialsManager extends Credential
     }
 };
 
+/**
+ * @returns {VmwareCredentialsManager}
+ */
 function getVmwareCredentialsManager() {
     if (!_vmwareCredentialsManager)
         _vmwareCredentialsManager = new VmwareCredentialsManager();

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
+ * parse:
-// @defaults-provided defaults object
+ *
-// @allowExtras: whether or not to allow properties not in @default
+ * @param {*} params caller-provided parameter object, or %null
-//
+ * @param {*} defaults provided defaults object
-// Examines @params and fills in default values from @defaults for
+ * @param {boolean} [allowExtras] whether or not to allow properties not in `default`
-// any properties in @defaults that don't appear in @params. If
+ *
-// @allowExtras is not %true, it will throw an error if @params
+ * @summary Examines `params` and fills in default values from `defaults` for
-// contains any properties that aren't in @defaults.
+ * any properties in `default` that don't appear in `params`. If
-//
+ * `allowExtras` is not %true, it will throw an error if `params`
-// If @params is %null, this returns the values from @defaults.
+ * contains any properties that aren't in `defaults`.
-//
+ *
-// Return value: a new object, containing the merged parameters from
+ * If `params` is %null, this returns the values from `defaults`.
-// @params and @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
+ * findUrls:
-//
+ *
-// Searches @str for URLs and returns an array of objects with %url
+ * @param {string} str string to find URLs in
-// properties showing the matched URL string, and %pos properties indicating
+ *
-// the position within @str where the URL was found.
+ * Searches `str` for URLs and returns an array of objects with %url
-//
+ * properties showing the matched URL string, and %pos properties indicating
-// Return value: the list of match objects, as described above
+ * 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
+ * spawn:
-//
+ *
-// Runs @argv in the background, handling any errors that occur
+ * Runs `argv` in the background, handling any errors that occur
-// when trying to start the program.
+ * 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
+ * spawnCommandLine:
-//
+ *
-// Runs @commandLine in the background, handling any errors that
+ * @param {readonly string[]} commandLine a command line
-// occur when trying to parse or start the program.
+ *
+ * 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
+ * spawnApp:
-//
+ *
-// Runs @argv as if it was an application, handling startup notification
+ * @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
+ * trySpawn:
-//
+ *
-// Runs @argv in the background. If launching @argv fails,
+ * @param {readonly string[]} argv an argv array
-// this will throw an error.
+ *
+ * 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
+ * trySpawnCommandLine:
-//
+ *
-// Runs @commandLine in the background. If launching @commandLine
+ * @param {readonly string[]} commandLine a command line
-// fails, this will throw an error.
+ *
+ * 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
+ * insertSorted:
-// @val: a value to insert
+ *
-// @cmp: the sorting function
+ * @template T, [K=T]
-//
+ * @param {T[]} array an array sorted according to `cmp`
-// Inserts @val into @array, preserving the
+ * @param {K} val a value to insert
-// sorting invariants.
+ * @param {(a: T, val: K) => number} cmp the sorting function
-// Returns the position at which it was inserted
+ * @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
+ * _GNOMEversionToNumber:
-//
+ *
-// Like Number() but returns sortable values for special-cases
+ * @param {string} version a GNOME version element
-// 'alpha' and 'beta'. Returns NaN for unhandled 'versions'.
+ * @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
+ * GNOMEversionCompare:
-// @version2: a string containing another GNOME version
+ *
-//
+ * @param {string} version1 a string containing a GNOME version
-// Returns an integer less than, equal to, or greater than
+ * @param {string} version2 a string containing another GNOME version
-// zero, if version1 is older, equal or newer than version2
+ * @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('.');

js/ui/accessDialog.js

@@ -16,6 +16,7 @@ const { loadInterfaceXML } = imports.misc.fileUtils;
 const RequestIface = loadInterfaceXML('org.freedesktop.impl.portal.Request');
 const AccessIface = loadInterfaceXML('org.freedesktop.impl.portal.Access');
 
+/** @enum {number} */
 var DialogResponse = {
     OK: 0,
     CANCEL: 1,

js/ui/altTab.js

@@ -26,6 +26,7 @@ var APP_ICON_SIZE_SMALL = 48;
 
 const baseIconSizes = [96, 64, 48, 32, 22];
 
+/** @enum {number} */
 var AppIconMode = {
     THUMBNAIL_ONLY: 1,
     APP_ICON_ONLY: 2,
@@ -294,27 +295,28 @@ class AppSwitcherPopup extends SwitcherPopup.SwitcherPopup {
 
     /**
      * _select:
-     * @param {number} app: index of the app to select
-     * @param {number=} window: index of which of @app's windows to select
-     * @param {bool} forceAppFocus: optional flag, see below
      *
-     * Selects the indicated @app, and optional @window, and sets
+     * @param {number} app index of the app to select
+     * @param {number} [window] index of which of `app`'s windows to select
+     * @param {boolean} [forceAppFocus] optional flag, see below
+     *
+     * Selects the indicated `app`, and optional `window`, and sets
      * this._thumbnailsFocused appropriately to indicate whether the
      * arrow keys should act on the app list or the thumbnail list.
      *
-     * If @app is specified and @window is unspecified or %null, then
+     * If `app` is specified and `window` is unspecified or %null, then
      * the app is highlighted (ie, given a light background), and the
-     * current thumbnail list, if any, is destroyed. If @app has
+     * current thumbnail list, if any, is destroyed. If `app` has
-     * multiple windows, and @forceAppFocus is not %true, then a
+     * multiple windows, and `forceAppFocus` is not %true, then a
      * timeout is started to open a thumbnail list.
      *
-     * If @app and @window are specified (and @forceAppFocus is not),
+     * If `app` and `window` are specified (and `forceAppFocus` is not),
-     * then @app will be outlined, a thumbnail list will be created
+     * then `app` will be outlined, a thumbnail list will be created
-     * and focused (if it hasn't been already), and the @window'th
+     * and focused (if it hasn't been already), and the `window`'th
      * window in it will be highlighted.
      *
-     * If @app and @window are specified and @forceAppFocus is %true,
+     * If `app` and `window` are specified and `forceAppFocus` is %true,
-     * then @app will be highlighted, and @window outlined, and the
+     * then `app` will be highlighted, and `window` outlined, and the
      * app list will have the keyboard focus.
      */
     _select(app, window, forceAppFocus) {

js/ui/appFavorites.js

@@ -206,6 +206,10 @@ class AppFavorites extends Signals.EventEmitter {
 }
 
 var appFavoritesInstance = null;
+
+/**
+ * @returns {AppFavorites}
+ */
 function getAppFavorites() {
     if (appFavoritesInstance == null)
         appFavoritesInstance = new AppFavorites();

js/ui/background.js

@@ -229,6 +229,9 @@ var BackgroundCache = class BackgroundCache extends Signals.EventEmitter {
     }
 };
 
+/**
+ * @returns {BackgroundCache}
+ */
 function getBackgroundCache() {
     if (!_backgroundCache)
         _backgroundCache = new BackgroundCache();

js/ui/backgroundMenu.js

@@ -24,6 +24,10 @@ var BackgroundMenu = class BackgroundMenu extends PopupMenu.PopupMenu {
     }
 };
 
+/**
+ * @param {Meta.BackgroundActor} actor
+ * @param {import('./layout.js').LayoutManager} layoutManager
+ */
 function addBackgroundMenu(actor, layoutManager) {
     actor.reactive = true;
     actor._backgroundMenu = new BackgroundMenu(layoutManager);

js/ui/boxpointer.js

@@ -33,6 +33,10 @@ var POPUP_ANIMATION_TIME = 150;
 var BoxPointer = GObject.registerClass({
     Signals: { 'arrow-side-changed': {} },
 }, class BoxPointer extends St.Widget {
+    /**
+     * @param {*} arrowSide side to draw the arrow on
+     * @param {*} binProperties Properties to set on contained bin
+     */
     _init(arrowSide, binProperties) {
         super._init();
 

js/ui/calendar.js

@@ -109,10 +109,16 @@ var EventSourceBase = GObject.registerClass({
     },
     Signals: { 'changed': {} },
 }, class EventSourceBase extends GObject.Object {
+    /**
+     * @returns {boolean}
+     */
     get isLoading() {
         throw new GObject.NotImplementedError(`isLoading in ${this.constructor.name}`);
     }
 
+    /**
+     * @returns {boolean}
+     */
     get hasCalendars() {
         throw new GObject.NotImplementedError(`hasCalendars in ${this.constructor.name}`);
     }
@@ -128,6 +134,10 @@ var EventSourceBase = GObject.registerClass({
         throw new GObject.NotImplementedError(`getEvents in ${this.constructor.name}`);
     }
 
+    /**
+     * @param {Date} _day
+     * @returns {boolean}
+     */
     hasEvents(_day) {
         throw new GObject.NotImplementedError(`hasEvents in ${this.constructor.name}`);
     }

js/ui/components/autorunManager.js

@@ -21,6 +21,7 @@ const SETTING_START_APP = 'autorun-x-content-start-app';
 const SETTING_IGNORE = 'autorun-x-content-ignore';
 const SETTING_OPEN_FOLDER = 'autorun-x-content-open-folder';
 
+/** @enum {number} */
 var AutorunSetting = {
     RUN: 0,
     IGNORE: 1,

js/ui/components/polkitAgent.js

@@ -18,6 +18,7 @@ const ShellEntry = imports.ui.shellEntry;
 const UserWidget = imports.ui.userWidget;
 const {wiggle} = imports.misc.animationUtils;
 
+/** @enum {number} */
 const DialogMode = {
     AUTH: 0,
     CONFIRM: 1,

js/ui/dash.js

@@ -21,6 +21,9 @@ var DASH_ITEM_LABEL_SHOW_TIME = 150;
 var DASH_ITEM_LABEL_HIDE_TIME = 100;
 var DASH_ITEM_HOVER_TIMEOUT = 300;
 
+/**
+ * @param {AppDisplay.AppIcon} source
+ */
 function getAppFromSource(source) {
     if (source instanceof AppDisplay.AppIcon)
         return source.app;

js/ui/dnd.js

@@ -18,14 +18,16 @@ var SNAP_BACK_ANIMATION_TIME = 250;
 // Time to animate to original position on success
 var REVERT_ANIMATION_TIME = 750;
 
-var DragMotionResult = {
+/** @enum {number} */
+varragMotionResult = {
     NO_DROP:   0,
     COPY_DROP: 1,
     MOVE_DROP: 2,
     CONTINUE:  3,
 };
 
-var DragState = {
+/** @enum {number} */
+varragState = {
     INIT:      0,
     DRAGGING:  1,
     CANCELLED: 2,
@@ -69,10 +71,21 @@ function _getRealActorScale(actor) {
     return scale;
 }
 
+/**
+ * @typedef {object} DragMonitor
+ * @property {Function} dragMotion
+ */
+
+/**
+ * @param {DragMonitor} monitor
+ */
 function addDragMonitor(monitor) {
     dragMonitors.push(monitor);
 }
 
+/**
+ * @param {DragMonitor} monitor
+ */
 function removeDragMonitor(monitor) {
     for (let i = 0; i < dragMonitors.length; i++) {
         if (dragMonitors[i] == monitor) {
@@ -857,9 +870,9 @@ var _Draggable = class _Draggable extends Signals.EventEmitter {
 
 /**
  * makeDraggable:
- * @param {Clutter.Actor} actor: Source actor
+ * @param {Clutter.Actor} actor Source actor
- * @param {Object=} params: Additional parameters
+ * @param {object} [params] Additional parameters
- * @returns {Object} a new Draggable
+ * @returns {_Draggable} a new Draggable
  *
  * Create an object which controls drag and drop for the given actor.
  *

js/ui/extensionDownloader.js

@@ -60,6 +60,9 @@ async function installExtension(uuid, invocation) {
     dialog.open(global.get_current_time());
 }
 
+/**
+ * @param {string} uuid
+ */
 function uninstallExtension(uuid) {
     let extension = Main.extensionManager.lookup(uuid);
     if (!extension)

js/ui/grabHelper.js

@@ -7,18 +7,22 @@ const St = imports.gi.St;
 const Main = imports.ui.main;
 const Params = imports.misc.params;
 
-// GrabHelper:
+/**
-// @owner: the actor that owns the GrabHelper
+ * GrabHelper:
-// @params: optional parameters to pass to Main.pushModal()
+ *
-//
+ * Creates a new GrabHelper object, for dealing with keyboard and pointer grabs
-// Creates a new GrabHelper object, for dealing with keyboard and pointer grabs
+ * associated with a set of actors.
-// associated with a set of actors.
+ *
-//
+ * Note that the grab can be automatically dropped at any time by the user, and
-// Note that the grab can be automatically dropped at any time by the user, and
+ * your code just needs to deal with it; you shouldn't adjust behavior directly
-// your code just needs to deal with it; you shouldn't adjust behavior directly
+ * after you call ungrab(), but instead pass an 'onUngrab' callback when you
-// after you call ungrab(), but instead pass an 'onUngrab' callback when you
+ * call grab().
-// call grab().
+ */
-var GrabHelper = class GrabHelper {
+class GrabHelper {
+    /**
+     * @param {Clutter.Actor} owner the actor that owns the GrabHelper
+     * @param {*} params optional parameters to pass to Main.pushModal()
+     */
     constructor(owner, params) {
         if (!(owner instanceof Clutter.Actor))
             throw new Error('GrabHelper owner must be a Clutter.Actor');

js/ui/iconGrid.js

@@ -15,6 +15,7 @@ var ICON_SIZE = 96;
 
 var PAGE_SWITCH_TIME = 300;
 
+/** @enum {number} */
 var IconSize = {
     LARGE: 96,
     MEDIUM: 64,
@@ -51,6 +52,7 @@ const defaultGridModes = [
 var LEFT_DIVIDER_LEEWAY = 20;
 var RIGHT_DIVIDER_LEEWAY = 20;
 
+/** @enum {number} */
 var DragLocation = {
     INVALID: 0,
     START_EDGE: 1,
@@ -174,6 +176,9 @@ class BaseIcon extends Shell.SquareBin {
     }
 });
 
+/**
+ * @param {Clutter.Actor} actor
+ */
 function zoomOutActor(actor) {
     let [x, y] = actor.get_transformed_position();
     zoomOutActorAtPos(actor, x, y);
@@ -818,16 +823,17 @@ var IconGridLayout = GObject.registerClass({
 
     /**
      * addItem:
-     * @param {Clutter.Actor} item: item to append to the grid
-     * @param {int} page: page number
-     * @param {int} index: position in the page
      *
-     * Adds @item to the grid. @item must not be part of the grid.
+     * @param {Clutter.Actor} item item to append to the grid
+     * @param {number} page page number
+     * @param {number} index position in the page
      *
-     * If @index exceeds the number of items per page, @item will
+     * Adds `item` to the grid. `item` must not be part of the grid.
+     *
+     * If `index` exceeds the number of items per page, `item` will
      * be added to the next page.
      *
-     * @page must be a number between 0 and the number of pages.
+     * `page` must be a number between 0 and the number of pages.
      * Adding to the page after next will create a new page.
      */
     addItem(item, page = -1, index = -1) {
@@ -851,7 +857,8 @@ var IconGridLayout = GObject.registerClass({
 
     /**
      * appendItem:
-     * @param {Clutter.Actor} item: item to append to the grid
+     *
+     * @param {Clutter.Actor} item item to append to the grid
      *
      * Appends @item to the grid. @item must not be part of the grid.
      */
@@ -861,11 +868,12 @@ var IconGridLayout = GObject.registerClass({
 
     /**
      * moveItem:
-     * @param {Clutter.Actor} item: item to move
-     * @param {int} newPage: new page of the item
-     * @param {int} newPosition: new page of the item
      *
-     * Moves @item to the grid. @item must be part of the grid.
+     * @param {Clutter.Actor} item item to move
+     * @param {number} newPage new page of the item
+     * @param {number} newPosition new page of the item
+     *
+     * Moves `item` to the grid. `item` must be part of the grid.
      */
     moveItem(item, newPage, newPosition) {
         if (!this._items.has(item))
@@ -883,9 +891,10 @@ var IconGridLayout = GObject.registerClass({
 
     /**
      * removeItem:
-     * @param {Clutter.Actor} item: item to remove from the grid
      *
-     * Removes @item to the grid. @item must be part of the grid.
+     * @param {Clutter.Actor} item item to remove from the grid
+     *
+     * Removes `item` to the grid. `item` must be part of the grid.
      */
     removeItem(item) {
         if (!this._items.has(item))
@@ -902,7 +911,8 @@ var IconGridLayout = GObject.registerClass({
 
     /**
      * getItemsAtPage:
-     * @param {int} pageIndex: page index
+     *
+     * @param {number} pageIndex page index
      *
      * Retrieves the children at page @pageIndex. Children may be invisible.
      *
@@ -917,12 +927,12 @@ var IconGridLayout = GObject.registerClass({
 
     /**
      * getItemPosition:
-     * @param {BaseIcon} item: the item
      *
-     * Retrieves the position of @item is its page, or -1 if @item is not
+     * Retrieves the position of `item` is its page, or -1 if `item` is not
      * part of the grid.
      *
-     * @returns {[int, int]} the page and position of @item
+     * @param {BaseIcon} item the item
+     * @returns {[number, number]} the page and position of `item`
      */
     getItemPosition(item) {
         if (!this._items.has(item))
@@ -936,11 +946,12 @@ var IconGridLayout = GObject.registerClass({
 
     /**
      * getItemAt:
-     * @param {int} page: the page
-     * @param {int} position: the position in page
      *
      * Retrieves the item at @page and @position.
      *
+     * @param {number} page the page
+     * @param {number} position the position in page
+     *
      * @returns {BaseItem} the item at @page and @position, or null
      */
     getItemAt(page, position) {
@@ -957,11 +968,12 @@ var IconGridLayout = GObject.registerClass({
 
     /**
      * getItemPage:
-     * @param {BaseIcon} item: the item
      *
-     * Retrieves the page @item is in, or -1 if @item is not part of the grid.
+     * Retrieves the page `item` is in, or -1 if `item` is not part of the grid.
      *
-     * @returns {int} the page where @item is in
+     * @param {BaseIcon} item the item
+     *
+     * @returns {number} the page where `item` is in
      */
     getItemPage(item) {
         if (!this._items.has(item))
@@ -1010,14 +1022,15 @@ var IconGridLayout = GObject.registerClass({
 
     /**
      * getDropTarget:
-     * @param {int} x: position of the horizontal axis
-     * @param {int} y: position of the vertical axis
      *
-     * Retrieves the item located at (@x, @y), as well as the drag location.
+     * Retrieves the item located at (`x`, `y`), as well as the drag location.
-     * Both @x and @y are relative to the grid.
+     * Both `x` and `y` are relative to the grid.
      *
-     * @returns {[Clutter.Actor, DragLocation]} the item and drag location
+     * @param {number} x position of the horizontal axis
-     * under (@x, @y)
+     * @param {number} y position of the vertical axis
+     *
+     * @returns {[BaseIcon | null, DragLocation]} the item and drag location
+     * under (`x`, `y`)
      */
     getDropTarget(x, y) {
         const childSize = this._getChildrenMaxSize();
@@ -1269,16 +1282,17 @@ var IconGrid = GObject.registerClass({
 
     /**
      * addItem:
-     * @param {Clutter.Actor} item: item to append to the grid
-     * @param {int} page: page number
-     * @param {int} index: position in the page
      *
-     * Adds @item to the grid. @item must not be part of the grid.
+     * @param {BaseItem} item item to append to the grid
+     * @param {number} page page number
+     * @param {number} index position in the page
      *
-     * If @index exceeds the number of items per page, @item will
+     * Adds `item` to the grid. `item` must not be part of the grid.
+     *
+     * If `index` exceeds the number of items per page, `item` will
      * be added to the next page.
      *
-     * @page must be a number between 0 and the number of pages.
+     * `page` must be a number between 0 and the number of pages.
      * Adding to the page after next will create a new page.
      */
     addItem(item, page = -1, index = -1) {
@@ -1290,9 +1304,10 @@ var IconGrid = GObject.registerClass({
 
     /**
      * appendItem:
-     * @param {Clutter.Actor} item: item to append to the grid
      *
-     * Appends @item to the grid. @item must not be part of the grid.
+     * @param {Clutter.Actor} item item to append to the grid
+     *
+     * Appends `item` to the grid. `item` must not be part of the grid.
      */
     appendItem(item) {
         this.layout_manager.appendItem(item);
@@ -1300,11 +1315,12 @@ var IconGrid = GObject.registerClass({
 
     /**
      * moveItem:
-     * @param {Clutter.Actor} item: item to move
-     * @param {int} newPage: new page of the item
-     * @param {int} newPosition: new page of the item
      *
-     * Moves @item to the grid. @item must be part of the grid.
+     * Moves `item` to the grid. `item` must be part of the grid.
+     *
+     * @param {Clutter.Actor} item item to move
+     * @param {number} newPage new page of the item
+     * @param {number} newPosition new page of the item
      */
     moveItem(item, newPage, newPosition) {
         this.layout_manager.moveItem(item, newPage, newPosition);
@@ -1313,9 +1329,10 @@ var IconGrid = GObject.registerClass({
 
     /**
      * removeItem:
-     * @param {Clutter.Actor} item: item to remove from the grid
      *
-     * Removes @item to the grid. @item must be part of the grid.
+     * Removes `item` to the grid. `item` must be part of the grid.
+     *
+     * @param {Clutter.Actor} item item to remove from the grid
      */
     removeItem(item) {
         if (!this.contains(item))
@@ -1326,11 +1343,12 @@ var IconGrid = GObject.registerClass({
 
     /**
      * goToPage:
-     * @param {int} pageIndex: page index
-     * @param {boolean} animate: animate the page transition
      *
-     * Moves the current page to @pageIndex. @pageIndex must be a valid page
+     * Moves the current page to `pageIndex`. `pageIndex` must be a valid page
      * number.
+     *
+     * @param {number} pageIndex page index
+     * @param {boolean} animate animate the page transition
      */
     goToPage(pageIndex, animate = true) {
         if (pageIndex >= this.nPages)
@@ -1366,11 +1384,12 @@ var IconGrid = GObject.registerClass({
 
     /**
      * getItemPage:
-     * @param {BaseIcon} item: the item
      *
-     * Retrieves the page @item is in, or -1 if @item is not part of the grid.
+     * Retrieves the page `item` is in, or -1 if `item` is not part of the grid.
      *
-     * @returns {int} the page where @item is in
+     * @param {BaseIcon} item the item
+     *
+     * @returns {number} the page where `item` is in
      */
     getItemPage(item) {
         return this.layout_manager.getItemPage(item);
@@ -1378,12 +1397,13 @@ var IconGrid = GObject.registerClass({
 
     /**
      * getItemPosition:
-     * @param {BaseIcon} item: the item
      *
-     * Retrieves the position of @item is its page, or -1 if @item is not
+     * Retrieves the position of `item` is its page, or -1 if `item` is not
      * part of the grid.
      *
-     * @returns {[int, int]} the page and position of @item
+     * @param {BaseIcon} item the item
+     *
+     * @returns {[number, number]} the page and position of `item`
      */
     getItemPosition(item) {
         if (!this.contains(item))
@@ -1395,12 +1415,13 @@ var IconGrid = GObject.registerClass({
 
     /**
      * getItemAt:
-     * @param {int} page: the page
-     * @param {int} position: the position in page
      *
-     * Retrieves the item at @page and @position.
+     * Retrieves the item at `page` and `position`.
      *
-     * @returns {BaseItem} the item at @page and @position, or null
+     * @param {number} page the page
+     * @param {number} position the position in page
+     *
+     * @returns {BaseItem} the item at `page` and `position`, or null
      */
     getItemAt(page, position) {
         const layoutManager = this.layout_manager;
@@ -1409,9 +1430,10 @@ var IconGrid = GObject.registerClass({
 
     /**
      * getItemsAtPage:
-     * @param {int} page: the page index
      *
-     * Retrieves the children at page @page, including invisible children.
+     * Retrieves the children at page `page`, including invisible children.
+     *
+     * @param {number} page the page index
      *
      * @returns {Array} an array of {Clutter.Actor}s
      */

js/ui/lightbox.js

@@ -88,27 +88,6 @@ var RadialShaderEffect = GObject.registerClass({
 
 /**
  * Lightbox:
- * @container: parent Clutter.Container
- * @params: (optional) additional parameters:
- *           - inhibitEvents: whether to inhibit events for @container
- *           - width: shade actor width
- *           - height: shade actor height
- *           - fadeFactor: fading opacity factor
- *           - radialEffect: whether to enable the GLSL radial effect
- *
- * Lightbox creates a dark translucent "shade" actor to hide the
- * contents of @container, and allows you to specify particular actors
- * in @container to highlight by bringing them above the shade. It
- * tracks added and removed actors in @container while the lightboxing
- * is active, and ensures that all actors are returned to their
- * original stacking order when the lightboxing is removed. (However,
- * if actors are restacked by outside code while the lightboxing is
- * active, the lightbox may later revert them back to their original
- * order.)
- *
- * By default, the shade window will have the height and width of
- * @container and will track any changes in its size. You can override
- * this by passing an explicit width and height in @params.
  */
 var Lightbox = GObject.registerClass({
     Properties: {
@@ -116,6 +95,29 @@ var Lightbox = GObject.registerClass({
             'active', 'active', 'active', GObject.ParamFlags.READABLE, false),
     },
 }, class Lightbox extends St.Bin {
+    /**
+     * Lightbox creates a dark translucent "shade" actor to hide the
+     * contents of `container`, and allows you to specify particular actors
+     * in `container` to highlight by bringing them above the shade. It
+     * tracks added and removed actors in `container` while the lightboxing
+     * is active, and ensures that all actors are returned to their
+     * original stacking order when the lightboxing is removed. (However,
+     * if actors are restacked by outside code while the lightboxing is
+     * active, the lightbox may later revert them back to their original
+     * order.)
+     *
+     * By default, the shade window will have the height and width of
+     * `container` and will track any changes in its size. You can override
+     * this by passing an explicit width and height in `params`.
+     *
+     * @param {Clutter.Container} container parent Clutter.Container
+     * @param {object} [params] additional parameters:
+     * @param {boolean=} params.inhibitEvents: whether to inhibit events for `container`
+     * @param {number=} params.width: shade actor width
+     * @param {number=} params.height: shade actor height
+     * @param {number=} params.fadeFactor: fading opacity factor
+     * @param {boolean=} params.radialEffect: whether to enable the GLSL radial effect
+     */
     _init(container, params) {
         params = Params.parse(params, {
             inhibitEvents: false,
@@ -251,11 +253,12 @@ var Lightbox = GObject.registerClass({
 
     /**
      * highlight:
-     * @param {Clutter.Actor=} window: actor to highlight
      *
      * Highlights the indicated actor and unhighlights any other
      * currently-highlighted actor. With no arguments or a false/null
      * argument, all actors will be unhighlighted.
+     *
+     * @param {Clutter.Actor=} window actor to highlight
      */
     highlight(window) {
         if (this._highlighted == window)

js/ui/magnifier.js

@@ -169,7 +169,8 @@ var Magnifier = class Magnifier extends Signals.EventEmitter {
     /**
      * setActive:
      * Show/hide all the zoom regions.
-     * @param {bool} activate: Boolean to activate or de-activate the magnifier.
+     *
+     * @param {boolean} activate Boolean to activate or de-activate the magnifier.
      */
     setActive(activate) {
         let isActive = this.isActive();
@@ -208,7 +209,8 @@ var Magnifier = class Magnifier extends Signals.EventEmitter {
 
     /**
      * isActive:
-     * @returns {bool} Whether the magnifier is active.
+     *
+     * @returns {boolean} Whether the magnifier is active.
      */
     isActive() {
         // Sufficient to check one ZoomRegion since Magnifier's active
@@ -245,7 +247,8 @@ var Magnifier = class Magnifier extends Signals.EventEmitter {
 
     /**
      * isTrackingMouse:
-     * @returns {bool} whether the magnifier is currently tracking the mouse
+     *
+     * @returns {boolean} whether the magnifier is currently tracking the mouse
      */
     isTrackingMouse() {
         return !!this._mouseTrackingId;
@@ -255,6 +258,8 @@ var Magnifier = class Magnifier extends Signals.EventEmitter {
      * scrollToMousePos:
      * Position all zoom regions' ROI relative to the current location of the
      * system pointer.
+     *
+     * @param {[xMouse: number, yMouse: number] | []} args
      */
     scrollToMousePos(...args) {
         const [xMouse, yMouse] = args.length ? args : global.get_pointer();
@@ -279,15 +284,16 @@ var Magnifier = class Magnifier extends Signals.EventEmitter {
     /**
      * createZoomRegion:
      * Create a ZoomRegion instance with the given properties.
-     * @param {number} xMagFactor:
+     *
+     * @param {number} xMagFactor
      *     The power to set horizontal magnification of the ZoomRegion. A value
      *     of 1.0 means no magnification, a value of 2.0 doubles the size.
-     * @param {number} yMagFactor:
+     * @param {number} yMagFactor
      *    The power to set the vertical magnification of the ZoomRegion.
-     * @param {{x: number, y: number, width: number, height: number}} roi:
+     * @param {{x: number, y: number, width: number, height: number}} roi
      *    The reg Object that defines the region to magnify, given in
      *    unmagnified coordinates.
-     * @param {{x: number, y: number, width: number, height: number}} viewPort:
+     * @param {{x: number, y: number, width: number, height: number}} viewPort
      *     Object that defines the position of the ZoomRegion on screen.
      * @returns {ZoomRegion} the newly created ZoomRegion.
      */
@@ -309,7 +315,8 @@ var Magnifier = class Magnifier extends Signals.EventEmitter {
      * addZoomRegion:
      * Append the given ZoomRegion to the list of currently defined ZoomRegions
      * for this Magnifier instance.
-     * @param {ZoomRegion} zoomRegion: The zoomRegion to add.
+     *
+     * @param {ZoomRegion} zoomRegion The zoomRegion to add.
      */
     addZoomRegion(zoomRegion) {
         if (zoomRegion) {
@@ -322,7 +329,8 @@ var Magnifier = class Magnifier extends Signals.EventEmitter {
     /**
      * getZoomRegions:
      * Return a list of ZoomRegion's for this Magnifier.
-     * @returns {number[]} The Magnifier's zoom region list.
+     *
+     * @returns {ZoomRegion[]} The Magnifier's zoom region list.
      */
     getZoomRegions() {
         return this._zoomRegions;
@@ -369,8 +377,10 @@ var Magnifier = class Magnifier extends Signals.EventEmitter {
 
     /**
      * setCrosshairsVisible:
-     * Show or hide the cross hair.
+     *
-     * @param {bool} visible: Flag that indicates show (true) or hide (false).
+     * Show or hide the cross hair
+     *
+     * @param {boolean} visible Flag that indicates show (true) or hide (false).
      */
     setCrosshairsVisible(visible) {
         if (visible) {
@@ -386,8 +396,10 @@ var Magnifier = class Magnifier extends Signals.EventEmitter {
 
     /**
      * setCrosshairsColor:
+     *
      * Set the color of the crosshairs for all ZoomRegions.
-     * @param {string} color: The color as a string, e.g. '#ff0000ff' or 'red'.
+     *
+     * @param {string} color The color as a string, e.g. '#ff0000ff' or 'red'.
      */
     setCrosshairsColor(color) {
         if (this._crossHairs) {
@@ -399,6 +411,7 @@ var Magnifier = class Magnifier extends Signals.EventEmitter {
     /**
      * getCrosshairsColor:
      * Get the color of the crosshairs.
+     *
      * @returns {string} The color as a string, e.g. '#0000ffff' or 'blue'.
      */
     getCrosshairsColor() {
@@ -412,8 +425,10 @@ var Magnifier = class Magnifier extends Signals.EventEmitter {
 
     /**
      * setCrosshairsThickness:
+     *
      * Set the crosshairs thickness for all ZoomRegions.
-     * @param {number} thickness: The width of the vertical and
+     *
+     * @param {number} thickness The width of the vertical and
      *     horizontal lines of the crosshairs.
      */
     setCrosshairsThickness(thickness) {
@@ -424,6 +439,7 @@ var Magnifier = class Magnifier extends Signals.EventEmitter {
     /**
      * getCrosshairsThickness:
      * Get the crosshairs thickness.
+     *
      * @returns {number} The width of the vertical and horizontal
      *     lines of the crosshairs.
      */
@@ -436,7 +452,8 @@ var Magnifier = class Magnifier extends Signals.EventEmitter {
 
     /**
      * setCrosshairsOpacity:
-     * @param {number} opacity: Value between 0.0 (transparent)
+     *
+     * @param {number} opacity Value between 0.0 (transparent)
      *     and 1.0 (fully opaque).
      */
     setCrosshairsOpacity(opacity) {
@@ -457,8 +474,10 @@ var Magnifier = class Magnifier extends Signals.EventEmitter {
 
     /**
      * setCrosshairsLength:
+     *
      * Set the crosshairs length for all ZoomRegions.
-     * @param {number} length: The length of the vertical and horizontal
+     *
+     * @param {number} length The length of the vertical and horizontal
      *     lines making up the crosshairs.
      */
     setCrosshairsLength(length) {
@@ -471,6 +490,7 @@ var Magnifier = class Magnifier extends Signals.EventEmitter {
     /**
      * getCrosshairsLength:
      * Get the crosshairs length.
+     *
      * @returns {number} The length of the vertical and horizontal
      *     lines making up the crosshairs.
      */
@@ -483,8 +503,10 @@ var Magnifier = class Magnifier extends Signals.EventEmitter {
 
     /**
      * setCrosshairsClip:
+     *
      * Set whether the crosshairs are clipped at their intersection.
-     * @param {bool} clip: Flag to indicate whether to clip the crosshairs.
+     *
+     * @param {boolean} clip Flag to indicate whether to clip the crosshairs.
      */
     setCrosshairsClip(clip) {
         if (!this._crossHairs)
@@ -497,7 +519,8 @@ var Magnifier = class Magnifier extends Signals.EventEmitter {
     /**
      * getCrosshairsClip:
      * Get whether the crosshairs are clipped by the mouse image.
-     * @returns {bool} Whether the crosshairs are clipped.
+     *
+     * @returns {boolean} Whether the crosshairs are clipped.
      */
     getCrosshairsClip() {
         if (this._crossHairs) {
@@ -933,7 +956,8 @@ var ZoomRegion = class ZoomRegion {
 
     /**
      * setActive:
-     * @param {bool} activate: Boolean to show/hide the ZoomRegion.
+     *
+     * @param {boolean} activate Boolean to show/hide the ZoomRegion.
      */
     setActive(activate) {
         if (activate == this.isActive())
@@ -960,7 +984,8 @@ var ZoomRegion = class ZoomRegion {
 
     /**
      * isActive:
-     * @returns {bool} Whether this ZoomRegion is active
+     *
+     * @returns {boolean} Whether this ZoomRegion is active
      */
     isActive() {
         return this._magView != null;
@@ -968,10 +993,11 @@ var ZoomRegion = class ZoomRegion {
 
     /**
      * setMagFactor:
-     * @param {number} xMagFactor: The power to set the horizontal
+     *
+     * @param {number} xMagFactor The power to set the horizontal
      *     magnification factor to of the magnified view. A value of 1.0
      *     means no magnification. A value of 2.0 doubles the size.
-     * @param {number} yMagFactor: The power to set the vertical
+     * @param {number} yMagFactor The power to set the vertical
      *     magnification factor to of the magnified view.
      */
     setMagFactor(xMagFactor, yMagFactor) {
@@ -985,6 +1011,7 @@ var ZoomRegion = class ZoomRegion {
 
     /**
      * getMagFactor:
+     *
      * @returns {number[]} an array, [xMagFactor, yMagFactor], containing
      *     the horizontal and vertical magnification powers. A value of
      *     1.0 means no magnification. A value of 2.0 means the contents
@@ -996,7 +1023,8 @@ var ZoomRegion = class ZoomRegion {
 
     /**
      * setMouseTrackingMode
-     * @param {GDesktopEnums.MagnifierMouseTrackingMode} mode: the new mode
+     *
+     * @param {GDesktopEnums.MagnifierMouseTrackingMode} mode the new mode
      */
     setMouseTrackingMode(mode) {
         if (mode >= GDesktopEnums.MagnifierMouseTrackingMode.NONE &&
@@ -1005,7 +1033,8 @@ var ZoomRegion = class ZoomRegion {
     }
 
     /**
-     * getMouseTrackingMode
+     * getMouseTrackingMode:
+     *
      * @returns {GDesktopEnums.MagnifierMouseTrackingMode} the current mode
      */
     getMouseTrackingMode() {
@@ -1014,7 +1043,8 @@ var ZoomRegion = class ZoomRegion {
 
     /**
      * setFocusTrackingMode
-     * @param {GDesktopEnums.MagnifierFocusTrackingMode} mode: the new mode
+     *
+     * @param {GDesktopEnums.MagnifierFocusTrackingMode} mode the new mode
      */
     setFocusTrackingMode(mode) {
         this._focusTrackingMode = mode;
@@ -1023,7 +1053,8 @@ var ZoomRegion = class ZoomRegion {
 
     /**
      * setCaretTrackingMode
-     * @param {GDesktopEnums.MagnifierCaretTrackingMode} mode: the new mode
+     *
+     * @param {GDesktopEnums.MagnifierCaretTrackingMode} mode the new mode
      */
     setCaretTrackingMode(mode) {
         this._caretTrackingMode = mode;
@@ -1053,7 +1084,8 @@ var ZoomRegion = class ZoomRegion {
     /**
      * setViewPort
      * Sets the position and size of the ZoomRegion on screen.
-     * @param {{x: number, y: number, width: number, height: number}} viewPort:
+     *
+     * @param {{x: number, y: number, width: number, height: number}} viewPort
      *     Object defining the position and size of the view port.
      *     The values are in stage coordinate space.
      */
@@ -1065,7 +1097,8 @@ var ZoomRegion = class ZoomRegion {
     /**
      * setROI
      * Sets the "region of interest" that the ZoomRegion is magnifying.
-     * @param {{x: number, y: number, width: number, height: number}} roi:
+     *
+     * @param {{x: number, y: number, width: number, height: number}} roi
      *     Object that defines the region of the screen to magnify.
      *     The values are in screen (unmagnified) coordinate space.
      */
@@ -1087,6 +1120,7 @@ var ZoomRegion = class ZoomRegion {
      * Retrieves the "region of interest" -- the rectangular bounds of that part
      * of the desktop that the magnified view is showing (x, y, width, height).
      * The bounds are given in non-magnified coordinates.
+     *
      * @returns {number[]} an array, [x, y, width, height], representing
      *     the bounding rectangle of what is shown in the magnified view.
      */
@@ -1103,9 +1137,11 @@ var ZoomRegion = class ZoomRegion {
 
     /**
      * setLensMode:
+     *
      *  Turn lens mode on/off.  In full screen mode, lens mode does nothing since
      * a lens the size of the screen is pointless.
-     * @param {bool} lensMode: Whether lensMode should be active
+     *
+     * @param {boolean} lensMode Whether lensMode should be active
      */
     setLensMode(lensMode) {
         this._lensMode = lensMode;
@@ -1116,7 +1152,8 @@ var ZoomRegion = class ZoomRegion {
     /**
      * isLensMode:
      * Is lens mode on or off?
-     * @returns {bool} The lens mode state.
+     *
+     * @returns {boolean} The lens mode state.
      */
     isLensMode() {
         return this._lensMode;
@@ -1126,7 +1163,8 @@ var ZoomRegion = class ZoomRegion {
      * setClampScrollingAtEdges:
      * Stop vs. allow scrolling of the magnified contents when it scroll beyond
      * the edges of the screen.
-     * @param {bool} clamp: Boolean to turn on/off clamping.
+     *
+     *  @param {boolean} clamp Boolean to turn on/off clamping.
      */
     setClampScrollingAtEdges(clamp) {
         this._clampScrollingAtEdges = clamp;
@@ -1210,7 +1248,8 @@ var ZoomRegion = class ZoomRegion {
      * setScreenPosition:
      * Positions the zoom region to one of the enumerated positions on the
      * screen.
-     * @param {GDesktopEnums.MagnifierScreenPosition} inPosition: the position
+     *
+     *  @param {GDesktopEnums.MagnifierScreenPosition} inPosition the position
      */
     setScreenPosition(inPosition) {
         switch (inPosition) {
@@ -1236,6 +1275,7 @@ var ZoomRegion = class ZoomRegion {
      * getScreenPosition:
      * Tell the outside world what the current mode is -- magnifiying the
      * top half, bottom half, etc.
+     *
      *  @returns {GDesktopEnums.MagnifierScreenPosition}: the current position.
      */
     getScreenPosition() {
@@ -1252,7 +1292,8 @@ var ZoomRegion = class ZoomRegion {
     /**
      * scrollToMousePos:
      * Set the region of interest based on the position of the system pointer.
-     * @returns {bool}: Whether the system mouse pointer is over the
+     *
+     *  @returns {boolean}: Whether the system mouse pointer is over the
      *     magnified view.
      */
     scrollToMousePos() {
@@ -1293,8 +1334,9 @@ var ZoomRegion = class ZoomRegion {
      * scrollContentsTo:
      * Shift the contents of the magnified view such it is centered on the given
      * coordinate.
-     * @param {number} x: The x-coord of the point to center on.
+     *
-     * @param {number} y: The y-coord of the point to center on.
+     *  @param {number} x The x-coord of the point to center on.
+     * @param {number} y The y-coord of the point to center on.
      */
     scrollContentsTo(x, y) {
         if (x < 0 || x > global.screen_width ||
@@ -1314,7 +1356,8 @@ var ZoomRegion = class ZoomRegion {
     /**
      * addCrosshairs:
      * Add crosshairs centered on the magnified mouse.
-     * @param {Crosshairs} crossHairs: Crosshairs instance
+     *
+     *  @param {Crosshairs} crossHairs Crosshairs instance
      */
     addCrosshairs(crossHairs) {
         this._crossHairs = crossHairs;
@@ -1328,7 +1371,8 @@ var ZoomRegion = class ZoomRegion {
     /**
      * setInvertLightness:
      * Set whether to invert the lightness of the magnified view.
-     * @param {bool} flag: whether brightness should be inverted
+     *
+     *  @param {boolean} flag whether brightness should be inverted
      */
     setInvertLightness(flag) {
         this._invertLightness = flag;
@@ -1338,8 +1382,10 @@ var ZoomRegion = class ZoomRegion {
 
     /**
      * getInvertLightness:
+     *
      * Retrieve whether the lightness is inverted.
-     * @returns {bool} whether brightness should be inverted
+     *
+     * @returns {boolean} whether brightness should be inverted
      */
     getInvertLightness() {
         return this._invertLightness;
@@ -1347,8 +1393,10 @@ var ZoomRegion = class ZoomRegion {
 
     /**
      * setColorSaturation:
+     *
      * Set the color saturation of the magnified view.
-     * @param {number} saturation: A value from 0.0 to 1.0 that defines
+     *
+     * @param {number} saturation A value from 0.0 to 1.0 that defines
      *     the color saturation, with 0.0 defining no color (grayscale),
      *     and 1.0 defining full color.
      */
@@ -1361,6 +1409,7 @@ var ZoomRegion = class ZoomRegion {
     /**
      * getColorSaturation:
      * Retrieve the color saturation of the magnified view.
+     *
      *  @returns {number} the color saturation
      */
     getColorSaturation() {
@@ -1370,7 +1419,8 @@ var ZoomRegion = class ZoomRegion {
     /**
      * setBrightness:
      * Alter the brightness of the magnified view.
-     * @param {Object} brightness: Object containing the contrast for the
+     *
+     *  @param {object} brightness Object containing the contrast for the
      *     red, green, and blue channels. Values of 0.0 represent "standard"
      *     brightness (no change), whereas values less or greater than
      *     0.0 indicate decreased or incresaed brightness, respectively.
@@ -1390,7 +1440,8 @@ var ZoomRegion = class ZoomRegion {
     /**
      * setContrast:
      * Alter the contrast of the magnified view.
-     * @param {Object} contrast: Object containing the contrast for the
+     *
+     *  @param {object} contrast Object containing the contrast for the
      *     red, green, and blue channels. Values of 0.0 represent "standard"
      *     contrast (no change), whereas values less or greater than
      *     0.0 indicate decreased or incresaed contrast, respectively.
@@ -1410,6 +1461,7 @@ var ZoomRegion = class ZoomRegion {
     /**
      * getContrast:
      * Retrieve the contrast of the magnified view.
+     *
      *  @returns {{r: number, g: number, b: number}}: Object containing
      *     the contrast for the red, green, and blue channels.
      */
@@ -1768,7 +1820,7 @@ var ZoomRegion = class ZoomRegion {
         this._background.set_size(global.screen_width, global.screen_height);
         this._updateScreenPosition();
     }
-};
+}
 
 var Crosshairs = GObject.registerClass(
 class Crosshairs extends Clutter.Actor {
@@ -1819,9 +1871,10 @@ class Crosshairs extends Clutter.Actor {
     * already part of some other ZoomRegion, create a clone of the crosshairs
     * actor, and add the clone instead.  Returns either the original or the
     * clone.
-    * @param {ZoomRegion} zoomRegion: The container to add the crosshairs
+    *
+    * @param {ZoomRegion} zoomRegion The container to add the crosshairs
     *     group to.
-    * @param {Clutter.Actor} magnifiedMouse: The mouse actor for the
+    * @param {Clutter.Actor} magnifiedMouse The mouse actor for the
     *     zoom region -- used to position the crosshairs and properly
     *     layer them below the mouse.
     * @returns {Clutter.Actor} The crosshairs actor, or its clone.
@@ -1853,10 +1906,12 @@ class Crosshairs extends Clutter.Actor {
 
     /**
      * removeFromParent:
-     * @param {Clutter.Actor} childActor: the actor returned from
+     *
-     *     addToZoomRegion
      * Remove the crosshairs actor from its parent container, or destroy the
      * child actor if it was just a clone of the crosshairs actor.
+     *
+     * @param {Clutter.Actor} childActor the actor returned from
+     *     addToZoomRegion
      */
     removeFromParent(childActor) {
         if (childActor == this)
@@ -1868,7 +1923,8 @@ class Crosshairs extends Clutter.Actor {
     /**
      * setColor:
      * Set the color of the crosshairs.
-     * @param {Clutter.Color} clutterColor: The color
+     *
+     *  @param {Clutter.Color} clutterColor The color
      */
     setColor(clutterColor) {
         this._horizLeftHair.background_color = clutterColor;
@@ -1880,6 +1936,7 @@ class Crosshairs extends Clutter.Actor {
     /**
      * getColor:
      * Get the color of the crosshairs.
+     *
      * @returns {ClutterColor} the crosshairs color
      */
     getColor() {
@@ -1888,8 +1945,10 @@ class Crosshairs extends Clutter.Actor {
 
     /**
      * setThickness:
+     *
      * Set the width of the vertical and horizontal lines of the crosshairs.
-     * @param {number} thickness: the new thickness value
+     *
+     * @param {number} thickness the new thickness value
      */
     setThickness(thickness) {
         this._horizLeftHair.set_height(thickness);
@@ -1902,6 +1961,7 @@ class Crosshairs extends Clutter.Actor {
     /**
      * getThickness:
      * Get the width of the vertical and horizontal lines of the crosshairs.
+     *
      * @returns {number} The thickness of the crosshairs.
      */
     getThickness() {
@@ -1911,7 +1971,8 @@ class Crosshairs extends Clutter.Actor {
     /**
      * setOpacity:
      * Set how opaque the crosshairs are.
-     * @param {number} opacity: Value between 0 (fully transparent)
+     *
+     * @param {number} opacity Value between 0 (fully transparent)
      *     and 255 (full opaque).
      */
     setOpacity(opacity) {
@@ -1931,7 +1992,8 @@ class Crosshairs extends Clutter.Actor {
     /**
      * setLength:
      * Set the length of the vertical and horizontal lines in the crosshairs.
-     * @param {number} length: The length of the crosshairs.
+     *
+     * @param {number} length The length of the crosshairs.
      */
     setLength(length) {
         this._horizLeftHair.set_width(length);
@@ -1944,6 +2006,7 @@ class Crosshairs extends Clutter.Actor {
     /**
      * getLength:
      * Get the length of the vertical and horizontal lines in the crosshairs.
+     *
      * @returns {number} The length of the crosshairs.
      */
     getLength() {
@@ -1954,7 +2017,8 @@ class Crosshairs extends Clutter.Actor {
      * setClip:
      * Set the width and height of the rectangle that clips the crosshairs at
      * their intersection
-     * @param {number[]} size: Array of [width, height] defining the size
+     *
+     * @param {[number, number]} size Array of [width, height] defining the size
      *     of the clip rectangle.
      */
     setClip(size) {
@@ -1975,7 +2039,8 @@ class Crosshairs extends Clutter.Actor {
      * Reposition the horizontal and vertical hairs such that they cross at
      * the center of crosshairs group.  If called with the dimensions of
      * the clip rectangle, these are used to update the size of the clip.
-     * @param {number[]=} clipSize: If present, the clip's [width, height].
+     *
+     * @param {[number, number]} [clipSize] If present, the clip's [width, height].
      */
     reCenter(clipSize) {
         let [groupWidth, groupHeight] = this.get_size();
@@ -2000,7 +2065,7 @@ class Crosshairs extends Clutter.Actor {
     }
 });
 
-var MagShaderEffects = class MagShaderEffects {
+class MagShaderEffects {
     constructor(uiGroupClone) {
         this._inverse = new Shell.InvertLightnessEffect();
         this._brightnessContrast = new Clutter.BrightnessContrastEffect();
@@ -2032,7 +2097,8 @@ var MagShaderEffects = class MagShaderEffects {
     /**
      * setInvertLightness:
      * Enable/disable invert lightness effect.
-     * @param {bool} invertFlag: Enabled flag.
+     *
+     * @param {boolean} invertFlag Enabled flag.
      */
     setInvertLightness(invertFlag) {
         this._inverse.set_enabled(invertFlag);
@@ -2046,7 +2112,8 @@ var MagShaderEffects = class MagShaderEffects {
     /**
      * setBrightness:
      * Set the brightness of the magnified view.
-     * @param {Object} brightness: Object containing the contrast for the
+     *
+     * @param {object} brightness Object containing the contrast for the
      *     red, green, and blue channels. Values of 0.0 represent "standard"
      *     brightness (no change), whereas values less or greater than
      *     0.0 indicate decreased or incresaed brightness, respectively.
@@ -2071,7 +2138,8 @@ var MagShaderEffects = class MagShaderEffects {
 
     /**
      * Set the contrast of the magnified view.
-     * @param {Object} contrast: Object containing the contrast for the
+     *
+     * @param {object} contrast Object containing the contrast for the
      *     red, green, and blue channels. Values of 0.0 represent "standard"
      *     contrast (no change), whereas values less or greater than
      *     0.0 indicate decreased or incresaed contrast, respectively.
@@ -2096,4 +2164,4 @@ var MagShaderEffects = class MagShaderEffects {
             cRed !== NO_CHANGE || cGreen !== NO_CHANGE || cBlue !== NO_CHANGE ||
             bRed !== NO_CHANGE || bGreen !== NO_CHANGE || bBlue !== NO_CHANGE);
     }
-};
+}

js/ui/main.js

@@ -524,8 +524,9 @@ function loadTheme() {
 
 /**
  * notify:
- * @param {string} msg: A message
+ *
- * @param {string} details: Additional information
+ * @param {string} msg A message
+ * @param {string} details Additional information
  */
 function notify(msg, details) {
     let source = new MessageTray.SystemNotificationSource();
@@ -713,6 +714,11 @@ function popModal(grab, timestamp) {
     actionMode = Shell.ActionMode.NORMAL;
 }
 
+/**
+ * Creates the looking glass panel
+ *
+ * @returns {LookingGlass.LookingGlass}
+ */
 function createLookingGlass() {
     if (lookingGlass == null)
         lookingGlass = new LookingGlass.LookingGlass();
@@ -720,6 +726,9 @@ function createLookingGlass() {
     return lookingGlass;
 }
 
+/**
+ * Opens the run dialog
+ */
 function openRunDialog() {
     if (runDialog == null)
         runDialog = new RunDialog.RunDialog();
@@ -736,9 +745,10 @@ function openWelcomeDialog() {
 
 /**
  * activateWindow:
- * @param {Meta.Window} window: the window to activate
+ *
- * @param {number=} time: current event time
+ * @param {Meta.Window} window the window to activate
- * @param {number=} workspaceNum:  window's workspace number
+ * @param {number=} time current event time
+ * @param {number=} workspaceNum  window's workspace number
  *
  * Activates @window, switching to its workspace first if necessary,
  * and switching out of the overview if it's currently active
@@ -882,7 +892,8 @@ function initializeDeferredWork(actor, callback) {
 
 /**
  * queueDeferredWork:
- * @param {string} workId: work identifier
+ *
+ * @param {string} workId work identifier
  *
  * Ensure that the work identified by @workId will be
  * run on map or timeout. You should call this function

js/ui/messageList.js

@@ -17,6 +17,11 @@ var MESSAGE_ANIMATION_TIME = 100;
 
 var DEFAULT_EXPAND_LINES = 6;
 
+/**
+ * @param {string} text
+ * @param {boolean} allowMarkup
+ * @returns {string}
+ */
 function _fixMarkup(text, allowMarkup) {
     if (allowMarkup) {
         // Support &, ", ', < and >, escape all other

js/ui/messageTray.js

@@ -50,6 +50,7 @@ var State = {
 // notifications that were requested to be destroyed by the associated source,
 // and REPLACED for notifications that were destroyed as a consequence of a
 // newer version having replaced them.
+/** @enum {number} */
 var NotificationDestroyedReason = {
     EXPIRED: 1,
     DISMISSED: 2,
@@ -61,6 +62,7 @@ var NotificationDestroyedReason = {
 // urgency values map to the corresponding values for the notifications received
 // through the notification daemon. HIGH urgency value is used for chats received
 // through the Telepathy client.
+/** @enum {number} */
 var Urgency = {
     LOW: 0,
     NORMAL: 1,
@@ -74,6 +76,7 @@ var Urgency = {
 // contain information private to the physical system (for example, battery
 // status) and hence the same for every user. This affects whether the content
 // of a notification is shown on the lock screen.
+/** @enum {number} */
 var PrivacyScope = {
     USER: 0,
     SYSTEM: 1,

js/ui/modalDialog.js

@@ -16,6 +16,7 @@ const Params = imports.misc.params;
 var OPEN_AND_CLOSE_TIME = 100;
 var FADE_OUT_DIALOG_TIME = 1000;
 
+/** @enum {number} */
 var State = {
     OPENED: 0,
     CLOSED: 1,

js/ui/notificationDaemon.js

@@ -17,6 +17,7 @@ const { loadInterfaceXML } = imports.misc.fileUtils;
 
 const FdoNotificationsIface = loadInterfaceXML('org.freedesktop.Notifications');
 
+/** @enum {number} */
 var NotificationClosedReason = {
     EXPIRED: 1,
     DISMISSED: 2,
@@ -24,6 +25,7 @@ var NotificationClosedReason = {
     UNDEFINED: 4,
 };
 
+/** @enum {number} */
 var Urgency = {
     LOW: 0,
     NORMAL: 1,
@@ -544,9 +546,12 @@ function objectPathFromAppId(appId) {
     return `/${appId.replace(/\./g, '/').replace(/-/g, '_')}`;
 }
 
+/**
+ * @returns {{ 'desktop-startup-id': string }}
+ */
 function getPlatformData() {
     let startupId = GLib.Variant.new('s', `_TIME${global.get_current_time()}`);
-    return { "desktop-startup-id": startupId };
+    return {'desktop-startup-id': startupId};
 }
 
 function InvalidAppError() {}

js/ui/overviewControls.js

@@ -27,6 +27,7 @@ const A11Y_SCHEMA = 'org.gnome.desktop.a11y.keyboard';
 
 var SIDE_CONTROLS_ANIMATION_TIME = Overview.ANIMATION_TIME;
 
+/** @enum {number} */
 var ControlsState = {
     HIDDEN: 0,
     WINDOW_PICKER: 1,

js/ui/pointerWatcher.js

@@ -11,6 +11,10 @@ var IDLE_TIME = 1000;
 // but we turn off the polling when the user is idle.
 
 let _pointerWatcher = null;
+
+/**
+ * @returns {PointerWatcher}
+ */
 function getPointerWatcher() {
     if (_pointerWatcher == null)
         _pointerWatcher = new PointerWatcher();

js/ui/popupMenu.js

@@ -16,6 +16,7 @@ const BoxPointer = imports.ui.boxpointer;
 const Main = imports.ui.main;
 const Params = imports.misc.params;
 
+/** @enum {number} */
 var Ornament = {
     NONE: 0,
     DOT: 1,

js/ui/scripting.js

@@ -67,7 +67,9 @@ export const PerfHelperProxy = Gio.DBusProxy.makeProxyWrapper(PerfHelperIface);
 
 let _perfHelper = null;
 
-/** @private */
+/**
+ * @returns {PerfHelper}
+ */
 export async function _getPerfHelper() {
     if (_perfHelper == null) {
         _perfHelper = await PerfHelperProxy.newAsync(
@@ -87,12 +89,13 @@ export function _spawnPerfHelper() {
 
 /**
  * createTestWindow:
- * @param {Object} params: options for window creation.
+ *
- *   {number} [params.width=640] - width of window, in pixels
+ * @param {object} params options for window creation.
- *   {number} [params.height=480] - height of window, in pixels
+ * @param {number} [params.width=640] - width of window, in pixels
- *   {bool} [params.alpha=false] - whether the window should have an alpha channel
+ * @param {number} [params.height=480] - height of window, in pixels
- *   {bool} [params.maximized=false] - whether the window should be created maximized
+ * @param {boolean} [params.alpha=false] - whether the window should have an alpha channel
- *   {bool} [params.redraws=false] - whether the window should continually redraw itself
+ * @param {boolean} [params.maximized=false] - whether the window should be created maximized
+ * @param {boolean} [params.redraws=false] - whether the window should continually redraw itself
  * @returns {Promise}
  *
  * Creates a window using gnome-shell-perf-helper for testing purposes.
@@ -133,6 +136,7 @@ export async function waitTestWindows() {
 
 /**
  * destroyTestWindows:
+ *
  * @returns {Promise}
  *
  * Destroys all windows previously created with createTestWindow().
@@ -158,9 +162,10 @@ export async function disableHelperAutoExit() {
 }
 
 /**
- * defineScriptEvent
+ * defineScriptEvent:
- * @param {string} name: The event will be called script.<name>
+ *
- * @param {string} description: Short human-readable description of the event
+ * @param {string} name The event will be called script.<name>
+ * @param {string} description Short human-readable description of the event
  *
  * Convenience function to define a zero-argument performance event
  * within the 'script' namespace that is reserved for events defined locally
@@ -317,9 +322,6 @@ async function _runPerfScript(scriptModule, outputFile) {
 
 /**
  * runPerfScript
- * @param {Object} scriptModule: module object with run and finish
- *    functions and event handlers
- * @param {string} outputFile: path to write output to
  *
  * Runs a script for automated collection of performance data. The
  * script is defined as a Javascript module with specified contents.
@@ -350,11 +352,15 @@ async function _runPerfScript(scriptModule, outputFile) {
  *   '/ s', 'frames', 'frames / s', 'MiB / s / frame'
  *  value: computed value of the metric
  *
- * The resulting metrics will be written to @outputFile as JSON, or,
+ * The resulting metrics will be written to `outputFile` as JSON, or,
- * if @outputFile is not provided, logged.
+ * if `outputFile` is not provided, logged.
  *
  * After running the script and collecting statistics from the
  * event log, GNOME Shell will exit.
+ *
+ * @param {object} scriptModule module object with run and finish
+ *   functions and event handlers
+ * @param {string} outputFile path to write output to
  */
 export function runPerfScript(scriptModule, outputFile) {
     Shell.PerfLog.get_default().set_enabled(true);

js/ui/shellDBus.js

@@ -49,7 +49,7 @@ var GnomeShell = class {
 
     /**
      * Eval:
-     * @param {string} code: A string containing JavaScript code
+     * @param {string} code A string containing JavaScript code
      * @returns {Array}
      *
      * This function executes arbitrary code in the main

js/ui/shellEntry.js

@@ -131,6 +131,10 @@ function _onPopup(actor, entry) {
     entry.menu.open(BoxPointer.PopupAnimation.FULL);
 }
 
+/**
+ * @param {St.Entry} entry
+ * @param {*} params
+ */
 function addContextMenu(entry, params) {
     if (entry.menu)
         return;

js/ui/shellMountOperation.js

@@ -532,6 +532,7 @@ var ShellProcessesDialog = GObject.registerClass({
 
 const GnomeShellMountOpIface = loadInterfaceXML('org.Gtk.MountOperationHandler');
 
+/** @enum {number} */
 var ShellMountOperationType = {
     NONE: 0,
     ASK_PASSWORD: 1,

js/ui/status/keyboard.js

@@ -799,6 +799,9 @@ var InputSourceManager = class extends Signals.EventEmitter {
 
 let _inputSourceManager = null;
 
+/**
+ * @returns {InputSourceManager}
+ */
 function getInputSourceManager() {
     if (_inputSourceManager == null)
         _inputSourceManager = new InputSourceManager();

js/ui/status/location.js

@@ -22,6 +22,7 @@ const ENABLED = 'enabled';
 const APP_PERMISSIONS_TABLE = 'location';
 const APP_PERMISSIONS_ID = 'location';
 
+/** @enum {number} */
 var GeoclueAccuracyLevel = {
     NONE: 0,
     COUNTRY: 1,

js/ui/status/network.js

@@ -32,6 +32,7 @@ const MAX_VISIBLE_NETWORKS = 8;
 // small optimization, to avoid using [] all the time
 const NM80211Mode = NM['80211Mode'];
 
+/** @enum {number} */
 var PortalHelperResult = {
     CANCELLED: 0,
     COMPLETED: 1,

js/ui/status/rfkill.js

@@ -82,7 +82,11 @@ const RfkillManager = GObject.registerClass({
     }
 });
 
-var _manager;
+let _manager;
+
+/**
+ * @returns {RfkillManager}
+ */
 function getRfkillManager() {
     if (_manager != null)
         return _manager;

js/ui/status/thunderbolt.js

@@ -23,8 +23,7 @@ const BoltDeviceInterface = loadInterfaceXML('org.freedesktop.bolt1.Device');
 
 const BoltDeviceProxy = Gio.DBusProxy.makeProxyWrapper(BoltDeviceInterface);
 
-/*  */
+/** @enum {string} */
-
 var Status = {
     DISCONNECTED: 'disconnected',
     CONNECTING: 'connecting',
@@ -34,16 +33,19 @@ var Status = {
     AUTHORIZED: 'authorized',
 };
 
+/** @enum {string} */
 var Policy = {
     DEFAULT: 'default',
     MANUAL: 'manual',
     AUTO: 'auto',
 };
 
+/** @enum {string} */
 var AuthCtrl = {
     NONE: 'none',
 };
 
+/** @enum {string} */
 var AuthMode = {
     DISABLED: 'disabled',
     ENABLED: 'enabled',

js/ui/swipeTracker.js

@@ -37,6 +37,7 @@ const EPSILON = 0.005;
 
 const GESTURE_FINGER_COUNT = 3;
 
+/** @enum {number} */
 const State = {
     NONE: 0,
     SCROLLING: 1,
@@ -523,11 +524,11 @@ var SwipeTracker = GObject.registerClass({
 
     /**
      * canHandleScrollEvent:
-     * @param {Clutter.Event} scrollEvent: an event to check
-     * @returns {bool} whether the event can be handled by the tracker
-     *
      * This function can be used to combine swipe gesture and mouse
      * scrolling.
+     *
+     * @param {Clutter.Event} scrollEvent an event to check
+     * @returns {boolean} whether the event can be handled by the tracker
      */
     canHandleScrollEvent(scrollEvent) {
         if (!this.enabled || this._scrollGesture === null)

js/ui/switcherPopup.js

@@ -16,6 +16,11 @@ var POPUP_FADE_OUT_TIME = 100; // milliseconds
 var DISABLE_HOVER_TIMEOUT = 500; // milliseconds
 var NO_MODS_TIMEOUT = 1500; // milliseconds
 
+/**
+ * @param {number} a
+ * @param {number} b
+ * @returns {number}
+ */
 function mod(a, b) {
     return (a + b) % b;
 }
@@ -645,6 +650,10 @@ var SwitcherList = GObject.registerClass({
     }
 });
 
+/**
+ * @param {St.DrawingArrow} area
+ * @param {St.Side} side
+ */
 function drawArrow(area, side) {
     let themeNode = area.get_theme_node();
     let borderColor = themeNode.get_border_color(side);

js/ui/welcomeDialog.js

@@ -11,6 +11,7 @@ const Dialog = imports.ui.dialog;
 const Main = imports.ui.main;
 const ModalDialog = imports.ui.modalDialog;
 
+/** @enum {number} */
 var DialogResponse = {
     NO_THANKS: 0,
     TAKE_TOUR: 1,

js/ui/windowManager.js

@@ -161,6 +161,9 @@ class WindowDimmer extends Clutter.BrightnessContrastEffect {
     }
 });
 
+/**
+ * @param {Meta.WindowActor} actor
+ */
 function getWindowDimmer(actor) {
     let effect = actor.get_effect(WINDOW_DIMMER_EFFECT_NAME);
 

js/ui/workspacesView.js

@@ -82,6 +82,7 @@ var WorkspacesViewBase = GObject.registerClass({
     }
 });
 
+/** @enum {number} */
 var FitMode = {
     SINGLE: 0,
     ALL: 1,

subprojects/extensions-app/js/main.js

@@ -547,6 +547,8 @@ function initEnvironment() {
 }
 
 /**
+ * Main entrypoint for the app
+ *
  * @param {string[]} argv - command line arguments
  * @returns {void}
  */