From 64aa871a8acab1a79c1b708fee7b30b350b41c1a Mon Sep 17 00:00:00 2001 From: Evan Welsh Date: Sun, 30 Jul 2023 15:56:59 +0300 Subject: [PATCH] js: Add JSDoc to exported functions and fix incorrect JSDoc formatting Part-of: --- js/gdm/authPrompt.js | 3 + js/gdm/oVirt.js | 3 + js/gdm/util.js | 9 +- js/gdm/vmware.js | 3 + js/misc/config.js.in | 2 +- js/misc/extensionUtils.js | 3 + js/misc/fileUtils.js | 8 ++ js/misc/gnomeSession.js | 20 +++ js/misc/ibusManager.js | 3 + js/misc/keyboardManager.js | 6 + js/misc/loginManager.js | 6 +- js/misc/params.js | 31 +++-- js/misc/parentalControlsManager.js | 3 + js/misc/permissionStore.js | 5 + js/misc/smartcardManager.js | 3 + js/misc/systemActions.js | 3 + js/misc/util.js | 182 ++++++++++++++++--------- js/ui/accessDialog.js | 1 + js/ui/altTab.js | 26 ++-- js/ui/appFavorites.js | 4 + js/ui/background.js | 3 + js/ui/backgroundMenu.js | 4 + js/ui/boxpointer.js | 4 + js/ui/calendar.js | 10 ++ js/ui/components/autorunManager.js | 1 + js/ui/components/polkitAgent.js | 1 + js/ui/dash.js | 3 + js/ui/dnd.js | 23 +++- js/ui/extensionDownloader.js | 3 + js/ui/grabHelper.js | 28 ++-- js/ui/iconGrid.js | 136 +++++++++++-------- js/ui/lightbox.js | 47 ++++--- js/ui/magnifier.js | 188 ++++++++++++++++++-------- js/ui/main.js | 23 +++- js/ui/messageList.js | 5 + js/ui/messageTray.js | 3 + js/ui/modalDialog.js | 1 + js/ui/notificationDaemon.js | 7 +- js/ui/overviewControls.js | 1 + js/ui/pointerWatcher.js | 4 + js/ui/popupMenu.js | 1 + js/ui/scripting.js | 36 +++-- js/ui/shellDBus.js | 2 +- js/ui/shellEntry.js | 4 + js/ui/shellMountOperation.js | 1 + js/ui/status/keyboard.js | 3 + js/ui/status/location.js | 1 + js/ui/status/network.js | 1 + js/ui/status/rfkill.js | 6 +- js/ui/status/thunderbolt.js | 6 +- js/ui/swipeTracker.js | 7 +- js/ui/switcherPopup.js | 9 ++ js/ui/welcomeDialog.js | 1 + js/ui/windowManager.js | 3 + js/ui/workspacesView.js | 1 + subprojects/extensions-app/js/main.js | 2 + 56 files changed, 623 insertions(+), 280 deletions(-) diff --git a/js/gdm/authPrompt.js b/js/gdm/authPrompt.js index b10c26788..419a03606 100644 --- a/js/gdm/authPrompt.js +++ b/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, diff --git a/js/gdm/oVirt.js b/js/gdm/oVirt.js index 32e0aa528..7e829fbba 100644 --- a/js/gdm/oVirt.js +++ b/js/gdm/oVirt.js @@ -43,6 +43,9 @@ var OVirtCredentialsManager = class OVirtCredentialsManager extends Credential.C } }; +/** + * @returns {OVirtCredentialsManager} + */ function getOVirtCredentialsManager() { if (!_oVirtCredentialsManager) _oVirtCredentialsManager = new OVirtCredentialsManager(); diff --git a/js/gdm/util.js b/js/gdm/util.js index 18a6c09c0..8936e495b 100644 --- a/js/gdm/util.js +++ b/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, diff --git a/js/gdm/vmware.js b/js/gdm/vmware.js index 260b7c8e9..367ec4fc2 100644 --- a/js/gdm/vmware.js +++ b/js/gdm/vmware.js @@ -46,6 +46,9 @@ var VmwareCredentialsManager = class VmwareCredentialsManager extends Credential } }; +/** + * @returns {VmwareCredentialsManager} + */ function getVmwareCredentialsManager() { if (!_vmwareCredentialsManager) _vmwareCredentialsManager = new VmwareCredentialsManager(); diff --git a/js/misc/config.js.in b/js/misc/config.js.in index 5684ef69c..e7884bdd5 100644 --- a/js/misc/config.js.in +++ b/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') diff --git a/js/misc/extensionUtils.js b/js/misc/extensionUtils.js index d96716f62..06b0f8659 100644 --- a/js/misc/extensionUtils.js +++ b/js/misc/extensionUtils.js @@ -12,6 +12,9 @@ var ExtensionType = { PER_USER: 2, }; +/** + * @enum {number} + */ var ExtensionState = { ENABLED: 1, DISABLED: 2, diff --git a/js/misc/fileUtils.js b/js/misc/fileUtils.js index 75f1ee59c..31256294b 100644 --- a/js/misc/fileUtils.js +++ b/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); diff --git a/js/misc/gnomeSession.js b/js/misc/gnomeSession.js index 487644fe9..2b430342a 100644 --- a/js/misc/gnomeSession.js +++ b/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); } diff --git a/js/misc/ibusManager.js b/js/misc/ibusManager.js index 02c9af82a..ffba04d8c 100644 --- a/js/misc/ibusManager.js +++ b/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(); diff --git a/js/misc/keyboardManager.js b/js/misc/keyboardManager.js index 2f7e632cf..e5520dd34 100644 --- a/js/misc/keyboardManager.js +++ b/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(); diff --git a/js/misc/loginManager.js b/js/misc/loginManager.js index 6f3a8a55e..720a81137 100644 --- a/js/misc/loginManager.js +++ b/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) { diff --git a/js/misc/params.js b/js/misc/params.js index 817d66ceb..978cd0bd8 100644 --- a/js/misc/params.js +++ b/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) { diff --git a/js/misc/parentalControlsManager.js b/js/misc/parentalControlsManager.js index 42b8e793f..9c32b7f82 100644 --- a/js/misc/parentalControlsManager.js +++ b/js/misc/parentalControlsManager.js @@ -39,6 +39,9 @@ if (HAVE_MALCONTENT) { let _singleton = null; +/** + * @returns {ParentalControlsManager} + */ function getDefault() { if (_singleton === null) _singleton = new ParentalControlsManager(); diff --git a/js/misc/permissionStore.js b/js/misc/permissionStore.js index 46c5d5412..ae317398c 100644 --- a/js/misc/permissionStore.js +++ b/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', diff --git a/js/misc/smartcardManager.js b/js/misc/smartcardManager.js index 661b33771..c35a756d6 100644 --- a/js/misc/smartcardManager.js +++ b/js/misc/smartcardManager.js @@ -18,6 +18,9 @@ const SmartcardTokenIface = ` let _smartcardManager = null; +/** + * @returns {SmartcardManager} + */ function getSmartcardManager() { if (_smartcardManager == null) _smartcardManager = new SmartcardManager(); diff --git a/js/misc/systemActions.js b/js/misc/systemActions.js index 36da63cd9..2e984fa80 100644 --- a/js/misc/systemActions.js +++ b/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(); diff --git a/js/misc/util.js b/js/misc/util.js index 8dc6b9905..8654e4286 100644 --- a/js/misc/util.js +++ b/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('.'); diff --git a/js/ui/accessDialog.js b/js/ui/accessDialog.js index ee3bd7cbd..44f4f655f 100644 --- a/js/ui/accessDialog.js +++ b/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, diff --git a/js/ui/altTab.js b/js/ui/altTab.js index 7472729df..644a11dc2 100644 --- a/js/ui/altTab.js +++ b/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 - * multiple windows, and @forceAppFocus is not %true, then a + * current thumbnail list, if any, is destroyed. If `app` has + * 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), - * then @app will be outlined, a thumbnail list will be created - * and focused (if it hasn't been already), and the @window'th + * If `app` and `window` are specified (and `forceAppFocus` is not), + * then `app` will be outlined, a thumbnail list will be created + * 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, - * then @app will be highlighted, and @window outlined, and the + * If `app` and `window` are specified and `forceAppFocus` is %true, + * then `app` will be highlighted, and `window` outlined, and the * app list will have the keyboard focus. */ _select(app, window, forceAppFocus) { diff --git a/js/ui/appFavorites.js b/js/ui/appFavorites.js index ca6569503..a544672ce 100644 --- a/js/ui/appFavorites.js +++ b/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(); diff --git a/js/ui/background.js b/js/ui/background.js index 963050834..b7978ada6 100644 --- a/js/ui/background.js +++ b/js/ui/background.js @@ -229,6 +229,9 @@ var BackgroundCache = class BackgroundCache extends Signals.EventEmitter { } }; +/** + * @returns {BackgroundCache} + */ function getBackgroundCache() { if (!_backgroundCache) _backgroundCache = new BackgroundCache(); diff --git a/js/ui/backgroundMenu.js b/js/ui/backgroundMenu.js index 6725cc302..68fe6a67b 100644 --- a/js/ui/backgroundMenu.js +++ b/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); diff --git a/js/ui/boxpointer.js b/js/ui/boxpointer.js index bcd8a4c07..dbfde1953 100644 --- a/js/ui/boxpointer.js +++ b/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(); diff --git a/js/ui/calendar.js b/js/ui/calendar.js index d87d5aff8..6e7af8fea 100644 --- a/js/ui/calendar.js +++ b/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}`); } diff --git a/js/ui/components/autorunManager.js b/js/ui/components/autorunManager.js index cd9f697dc..5313cc473 100644 --- a/js/ui/components/autorunManager.js +++ b/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, diff --git a/js/ui/components/polkitAgent.js b/js/ui/components/polkitAgent.js index de2f86270..010dce8fd 100644 --- a/js/ui/components/polkitAgent.js +++ b/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, diff --git a/js/ui/dash.js b/js/ui/dash.js index 581054b69..be4b93eac 100644 --- a/js/ui/dash.js +++ b/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; diff --git a/js/ui/dnd.js b/js/ui/dnd.js index 457a66a91..2fee362c9 100644 --- a/js/ui/dnd.js +++ b/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 {Object=} params: Additional parameters - * @returns {Object} a new Draggable + * @param {Clutter.Actor} actor Source actor + * @param {object} [params] Additional parameters + * @returns {_Draggable} a new Draggable * * Create an object which controls drag and drop for the given actor. * diff --git a/js/ui/extensionDownloader.js b/js/ui/extensionDownloader.js index 317a13e62..64aba5a70 100644 --- a/js/ui/extensionDownloader.js +++ b/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) diff --git a/js/ui/grabHelper.js b/js/ui/grabHelper.js index 4ac5a01d5..6b8c2e1b5 100644 --- a/js/ui/grabHelper.js +++ b/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 -// @params: optional parameters to pass to Main.pushModal() -// -// Creates a new GrabHelper object, for dealing with keyboard and pointer grabs -// associated with a set of actors. -// -// 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 -// after you call ungrab(), but instead pass an 'onUngrab' callback when you -// call grab(). -var GrabHelper = class GrabHelper { +/** + * GrabHelper: + * + * Creates a new GrabHelper object, for dealing with keyboard and pointer grabs + * associated with a set of actors. + * + * 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 + * after you call ungrab(), but instead pass an 'onUngrab' callback when you + * call grab(). + */ +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'); diff --git a/js/ui/iconGrid.js b/js/ui/iconGrid.js index c239e27d2..289ab5398 100644 --- a/js/ui/iconGrid.js +++ b/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. - * Both @x and @y are relative to the grid. + * Retrieves the item located at (`x`, `y`), as well as the drag location. + * Both `x` and `y` are relative to the grid. * - * @returns {[Clutter.Actor, DragLocation]} the item and drag location - * under (@x, @y) + * @param {number} x position of the horizontal axis + * @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 */ diff --git a/js/ui/lightbox.js b/js/ui/lightbox.js index 1b02958b1..5f1ec8a7b 100644 --- a/js/ui/lightbox.js +++ b/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) diff --git a/js/ui/magnifier.js b/js/ui/magnifier.js index 3358d5aaa..9a5a7cdce 100644 --- a/js/ui/magnifier.js +++ b/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 + * + * 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,7 +1275,8 @@ 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. + * + * @returns {GDesktopEnums.MagnifierScreenPosition}: the current position. */ getScreenPosition() { return this._screenPosition; @@ -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,7 +1409,8 @@ var ZoomRegion = class ZoomRegion { /** * getColorSaturation: * Retrieve the color saturation of the magnified view. - * @returns {number} the color saturation + * + * @returns {number} the color saturation */ getColorSaturation() { return this._colorSaturation; @@ -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,7 +1461,8 @@ var ZoomRegion = class ZoomRegion { /** * getContrast: * Retrieve the contrast of the magnified view. - * @returns {{r: number, g: number, b: number}}: Object containing + * + * @returns {{r: number, g: number, b: number}}: Object containing * the contrast for the red, green, and blue channels. */ getContrast() { @@ -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); } -}; +} diff --git a/js/ui/main.js b/js/ui/main.js index a7d86b570..866811b18 100644 --- a/js/ui/main.js +++ b/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 {number=} workspaceNum: window's workspace number + * + * @param {Meta.Window} window the window to activate + * @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 diff --git a/js/ui/messageList.js b/js/ui/messageList.js index b77cf0961..a09cdc10d 100644 --- a/js/ui/messageList.js +++ b/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 diff --git a/js/ui/messageTray.js b/js/ui/messageTray.js index ca67d0092..a18ca2234 100644 --- a/js/ui/messageTray.js +++ b/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, diff --git a/js/ui/modalDialog.js b/js/ui/modalDialog.js index 7ddef070b..17d189175 100644 --- a/js/ui/modalDialog.js +++ b/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, diff --git a/js/ui/notificationDaemon.js b/js/ui/notificationDaemon.js index 7a8d61e48..253ef2c79 100644 --- a/js/ui/notificationDaemon.js +++ b/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() {} diff --git a/js/ui/overviewControls.js b/js/ui/overviewControls.js index c24416da1..68e59b794 100644 --- a/js/ui/overviewControls.js +++ b/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, diff --git a/js/ui/pointerWatcher.js b/js/ui/pointerWatcher.js index c346bb07e..68989f29b 100644 --- a/js/ui/pointerWatcher.js +++ b/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(); diff --git a/js/ui/popupMenu.js b/js/ui/popupMenu.js index ff503a142..7377f34e1 100644 --- a/js/ui/popupMenu.js +++ b/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, diff --git a/js/ui/scripting.js b/js/ui/scripting.js index fb31bab27..74e420899 100644 --- a/js/ui/scripting.js +++ b/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 - * {number} [params.height=480] - height of window, in pixels - * {bool} [params.alpha=false] - whether the window should have an alpha channel - * {bool} [params.maximized=false] - whether the window should be created maximized - * {bool} [params.redraws=false] - whether the window should continually redraw itself + * + * @param {object} params options for window creation. + * @param {number} [params.width=640] - width of window, in pixels + * @param {number} [params.height=480] - height of window, in pixels + * @param {boolean} [params.alpha=false] - whether the window should have an alpha channel + * @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 - * @param {string} name: The event will be called script. - * @param {string} description: Short human-readable description of the event + * defineScriptEvent: + * + * @param {string} name The event will be called script. + * @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, - * if @outputFile is not provided, logged. + * The resulting metrics will be written to `outputFile` as JSON, or, + * 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); diff --git a/js/ui/shellDBus.js b/js/ui/shellDBus.js index 8ee4e9b43..c36d3fd5b 100644 --- a/js/ui/shellDBus.js +++ b/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 diff --git a/js/ui/shellEntry.js b/js/ui/shellEntry.js index dab23ff86..e169648d7 100644 --- a/js/ui/shellEntry.js +++ b/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; diff --git a/js/ui/shellMountOperation.js b/js/ui/shellMountOperation.js index 591d88b1a..15afa7361 100644 --- a/js/ui/shellMountOperation.js +++ b/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, diff --git a/js/ui/status/keyboard.js b/js/ui/status/keyboard.js index b222574d2..7ba16c828 100644 --- a/js/ui/status/keyboard.js +++ b/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(); diff --git a/js/ui/status/location.js b/js/ui/status/location.js index a234bcfc0..eb0312d22 100644 --- a/js/ui/status/location.js +++ b/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, diff --git a/js/ui/status/network.js b/js/ui/status/network.js index eee89d021..1558ff57b 100644 --- a/js/ui/status/network.js +++ b/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, diff --git a/js/ui/status/rfkill.js b/js/ui/status/rfkill.js index edc8a9aa9..6056c9efd 100644 --- a/js/ui/status/rfkill.js +++ b/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; diff --git a/js/ui/status/thunderbolt.js b/js/ui/status/thunderbolt.js index 0ec4dab12..d3ecdcc48 100644 --- a/js/ui/status/thunderbolt.js +++ b/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', diff --git a/js/ui/swipeTracker.js b/js/ui/swipeTracker.js index 77ea6c273..e82f66e19 100644 --- a/js/ui/swipeTracker.js +++ b/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) diff --git a/js/ui/switcherPopup.js b/js/ui/switcherPopup.js index 4478b94f4..bc5438020 100644 --- a/js/ui/switcherPopup.js +++ b/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); diff --git a/js/ui/welcomeDialog.js b/js/ui/welcomeDialog.js index fdee845f8..4bd11ee5b 100644 --- a/js/ui/welcomeDialog.js +++ b/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, diff --git a/js/ui/windowManager.js b/js/ui/windowManager.js index 12787dc95..04826f013 100644 --- a/js/ui/windowManager.js +++ b/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); diff --git a/js/ui/workspacesView.js b/js/ui/workspacesView.js index 4e42977df..009d6703c 100644 --- a/js/ui/workspacesView.js +++ b/js/ui/workspacesView.js @@ -82,6 +82,7 @@ var WorkspacesViewBase = GObject.registerClass({ } }); +/** @enum {number} */ var FitMode = { SINGLE: 0, ALL: 1, diff --git a/subprojects/extensions-app/js/main.js b/subprojects/extensions-app/js/main.js index 98690d0e0..3f6c34a44 100644 --- a/subprojects/extensions-app/js/main.js +++ b/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} */