[gnome-shell] cleanup: Use JSDoc for documentation comments
- From: Georges Basile Stavracas Neto <gbsneto src gnome org>
- To: commits-list gnome org
- Cc:
- Subject: [gnome-shell] cleanup: Use JSDoc for documentation comments
- Date: Mon, 11 Nov 2019 20:54:50 +0000 (UTC)
commit 61210fdae146670cd710011717b4a1a89d71f932
Author: Florian Müllner <fmuellner gnome org>
Date: Thu Oct 17 18:41:52 2019 +0200
cleanup: Use JSDoc for documentation comments
It's a better fit than gtk-doc, and eslint can validate that they
are complete and use correct syntax.
https://gitlab.gnome.org/GNOME/gnome-shell/merge_requests/805
js/misc/extensionUtils.js | 13 +-
js/misc/loginManager.js | 3 +-
js/ui/altTab.js | 6 +-
js/ui/components/telepathyClient.js | 30 ++---
js/ui/dnd.js | 13 +-
js/ui/iconGrid.js | 7 +-
js/ui/lightbox.js | 2 +-
js/ui/magnifier.js | 233 +++++++++++++++++++-----------------
js/ui/magnifierDBus.js | 93 +++++++-------
js/ui/main.js | 39 +++---
js/ui/popupMenu.js | 4 +-
js/ui/scripting.js | 31 +++--
js/ui/shellDBus.js | 3 +-
js/ui/shellMountOperation.js | 59 ++++-----
14 files changed, 291 insertions(+), 245 deletions(-)
---
diff --git a/js/misc/extensionUtils.js b/js/misc/extensionUtils.js
index 37423d39a0..020042c8ae 100644
--- a/js/misc/extensionUtils.js
+++ b/js/misc/extensionUtils.js
@@ -36,7 +36,8 @@ const SERIALIZED_PROPERTIES = ['type', 'state', 'path', 'error', 'hasPrefs', 'ca
/**
* getCurrentExtension:
*
- * Returns the current extension, or null if not called from an extension.
+ * @returns {?object} - The current extension, or null if not called from
+ * an extension.
*/
function getCurrentExtension() {
let stack = (new Error()).stack.split('\n');
@@ -84,7 +85,7 @@ function getCurrentExtension() {
/**
* initTranslations:
- * @domain: (optional): the gettext domain to use
+ * @param {string=} domain - the gettext domain to use
*
* Initialize Gettext to load translations from extensionsdir/locale.
* If @domain is not provided, it will be taken from metadata['gettext-domain']
@@ -108,7 +109,8 @@ function initTranslations(domain) {
/**
* getSettings:
- * @schema: (optional): the GSettings schema id
+ * @param {string=} schema - the GSettings schema id
+ * @returns {Gio.Settings} - a new settings object for @schema
*
* Builds and returns a GSettings schema for @schema, using schema files
* in extensionsdir/schemas. If @schema is omitted, it is taken from
@@ -145,8 +147,9 @@ function getSettings(schema) {
/**
* versionCheck:
- * @required: an array of versions we're compatible with
- * @current: the version we have
+ * @param {string[]} required - an array of versions we're compatible with
+ * @param {string} current - the version we have
+ * @returns {bool} - true if @current is compatible with @required
*
* Check if a component is compatible for an extension.
* @required is an array, and at least one version must match.
diff --git a/js/misc/loginManager.js b/js/misc/loginManager.js
index 9ddc42856a..473ad0758d 100644
--- a/js/misc/loginManager.js
+++ b/js/misc/loginManager.js
@@ -74,8 +74,9 @@ function registerSessionWithGDM() {
let _loginManager = null;
/**
- * LoginManager:
+ * getLoginManager:
* An abstraction over systemd/logind and ConsoleKit.
+ * @returns {object} - the LoginManager singleton
*
*/
function getLoginManager() {
diff --git a/js/ui/altTab.js b/js/ui/altTab.js
index 741df63c46..855cd0e988 100644
--- a/js/ui/altTab.js
+++ b/js/ui/altTab.js
@@ -293,9 +293,9 @@ class AppSwitcherPopup extends SwitcherPopup.SwitcherPopup {
/**
* _select:
- * @app: index of the app to select
- * @window: (optional) index of which of @app's windows to select
- * @forceAppFocus: optional flag, see below
+ * @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
* this._thumbnailsFocused appropriately to indicate whether the
diff --git a/js/ui/components/telepathyClient.js b/js/ui/components/telepathyClient.js
index 9539900340..e6ea64224f 100644
--- a/js/ui/components/telepathyClient.js
+++ b/js/ui/components/telepathyClient.js
@@ -656,16 +656,16 @@ var ChatNotification = HAVE_TP ? GObject.registerClass({
/**
* appendMessage:
- * @message: An object with the properties:
- * text: the body of the message,
- * messageType: a #Tp.ChannelTextMessageType,
- * sender: the name of the sender,
- * timestamp: the time the message was sent
- * direction: a #NotificationDirection
+ * @param {Object} message: An object with the properties
+ * {string} message.text: the body of the message,
+ * {Tp.ChannelTextMessageType} message.messageType: the type
+ * {string} message.sender: the name of the sender,
+ * {number} message.timestamp: the time the message was sent
+ * {NotificationDirection} message.direction: a #NotificationDirection
*
- * @noTimestamp: Whether to add a timestamp. If %true, no timestamp
- * will be added, regardless of the difference since the
- * last timestamp
+ * @param {bool} noTimestamp: Whether to add a timestamp. If %true,
+ * no timestamp will be added, regardless of the difference since
+ * the last timestamp
*/
appendMessage(message, noTimestamp) {
let messageBody = GLib.markup_escape_text(message.text, -1);
@@ -720,13 +720,13 @@ var ChatNotification = HAVE_TP ? GObject.registerClass({
/**
* _append:
- * @props: An object with the properties:
- * body: The text of the message.
- * group: The group of the message, one of:
+ * @param {Object} props: An object with the properties:
+ * {string} props.body: The text of the message.
+ * {string} props.group: The group of the message, one of:
* 'received', 'sent', 'meta'.
- * styles: Style class names for the message to have.
- * timestamp: The timestamp of the message.
- * noTimestamp: suppress timestamp signal?
+ * {string[]} props.styles: Style class names for the message to have.
+ * {number} props.timestamp: The timestamp of the message.
+ * {bool} props.noTimestamp: suppress timestamp signal?
*/
_append(props) {
let currentTime = Date.now() / 1000;
diff --git a/js/ui/dnd.js b/js/ui/dnd.js
index 07de7ad4f7..75edfe7c26 100644
--- a/js/ui/dnd.js
+++ b/js/ui/dnd.js
@@ -292,9 +292,11 @@ var _Draggable = class _Draggable {
/**
* startDrag:
- * @stageX: X coordinate of event
- * @stageY: Y coordinate of event
- * @time: Event timestamp
+ * @param {number} stageX: X coordinate of event
+ * @param {number} stageY: Y coordinate of event
+ * @param {number} time: Event timestamp
+ * @param {Clutter.EventSequence=} sequence: Event sequence
+ * @param {Clutter.InputDevice=} device: device that originated the event
*
* Directly initiate a drag and drop operation from the given actor.
* This function is useful to call if you've specified manualMode
@@ -746,8 +748,9 @@ Signals.addSignalMethods(_Draggable.prototype);
/**
* makeDraggable:
- * @actor: Source actor
- * @params: (optional) Additional parameters
+ * @param {Clutter.Actor} actor: Source actor
+ * @param {Object=} params: Additional parameters
+ * @returns {Object} a new Draggable
*
* Create an object which controls drag and drop for the given actor.
*
diff --git a/js/ui/iconGrid.js b/js/ui/iconGrid.js
index ff3d79c330..6d6ff5cbe2 100644
--- a/js/ui/iconGrid.js
+++ b/js/ui/iconGrid.js
@@ -958,9 +958,10 @@ var PaginatedIconGrid = GObject.registerClass({
/**
* openExtraSpace:
- * @sourceItem: the item for which to create extra space
- * @side: where @sourceItem should be located relative to the created space
- * @nRows: the amount of space to create
+ * @param {Clutter.Actor} sourceItem: item for which to create extra space
+ * @param {St.Side} side: where @sourceItem should be located relative to
+ * the created space
+ * @param {number} nRows: the amount of space to create
*
* Pan view to create extra space for @nRows above or below @sourceItem.
*/
diff --git a/js/ui/lightbox.js b/js/ui/lightbox.js
index f482964255..5446696a8b 100644
--- a/js/ui/lightbox.js
+++ b/js/ui/lightbox.js
@@ -245,7 +245,7 @@ var Lightbox = GObject.registerClass({
/**
* highlight:
- * @window: actor to 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
diff --git a/js/ui/magnifier.js b/js/ui/magnifier.js
index 4bdd546ba0..9f8ee2825c 100644
--- a/js/ui/magnifier.js
+++ b/js/ui/magnifier.js
@@ -141,7 +141,7 @@ var Magnifier = class Magnifier {
/**
* setActive:
* Show/hide all the zoom regions.
- * @activate: Boolean to activate or de-activate the magnifier.
+ * @param {bool} activate: Boolean to activate or de-activate the magnifier.
*/
setActive(activate) {
let isActive = this.isActive();
@@ -177,7 +177,7 @@ var Magnifier = class Magnifier {
/**
* isActive:
- * @return Whether the magnifier is active (boolean).
+ * @returns {bool} Whether the magnifier is active.
*/
isActive() {
// Sufficient to check one ZoomRegion since Magnifier's active
@@ -212,7 +212,7 @@ var Magnifier = class Magnifier {
/**
* isTrackingMouse:
- * Is the magnifier tracking the mouse currently?
+ * @returns {bool} whether the magnifier is currently tracking the mouse
*/
isTrackingMouse() {
return !!this._mouseTrackingId;
@@ -222,7 +222,7 @@ var Magnifier = class Magnifier {
* scrollToMousePos:
* Position all zoom regions' ROI relative to the current location of the
* system pointer.
- * @return true.
+ * @returns {bool} true.
*/
scrollToMousePos() {
let [xMouse, yMouse] = global.get_pointer();
@@ -247,17 +247,17 @@ var Magnifier = class Magnifier {
/**
* createZoomRegion:
* Create a ZoomRegion instance with the given properties.
- * @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.
- * @yMagFactor: The power to set the vertical magnification of the
- * ZoomRegion.
- * @roi Object in the form { x, y, width, height } that
- * defines the region to magnify. Given in unmagnified
- * coordinates.
- * @viewPort Object in the form { x, y, width, height } that defines
- * the position of the ZoomRegion on screen.
- * @return The newly created ZoomRegion.
+ * @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:
+ * The power to set the vertical magnification of the ZoomRegion.
+ * @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:
+ * Object that defines the position of the ZoomRegion on screen.
+ * @returns {ZoomRegion} the newly created ZoomRegion.
*/
createZoomRegion(xMagFactor, yMagFactor, roi, viewPort) {
let zoomRegion = new ZoomRegion(this, this._cursorRoot);
@@ -277,7 +277,7 @@ var Magnifier = class Magnifier {
* addZoomRegion:
* Append the given ZoomRegion to the list of currently defined ZoomRegions
* for this Magnifier instance.
- * @zoomRegion: The zoomRegion to add.
+ * @param {ZoomRegion} zoomRegion: The zoomRegion to add.
*/
addZoomRegion(zoomRegion) {
if (zoomRegion) {
@@ -290,7 +290,7 @@ var Magnifier = class Magnifier {
/**
* getZoomRegions:
* Return a list of ZoomRegion's for this Magnifier.
- * @return: The Magnifier's zoom region list (array).
+ * @returns {number[]} The Magnifier's zoom region list.
*/
getZoomRegions() {
return this._zoomRegions;
@@ -338,7 +338,7 @@ var Magnifier = class Magnifier {
/**
* setCrosshairsVisible:
* Show or hide the cross hair.
- * @visible Flag that indicates show (true) or hide (false).
+ * @param {bool} visible: Flag that indicates show (true) or hide (false).
*/
setCrosshairsVisible(visible) {
if (visible) {
@@ -354,7 +354,7 @@ var Magnifier = class Magnifier {
/**
* setCrosshairsColor:
* Set the color of the crosshairs for all ZoomRegions.
- * @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) {
@@ -366,7 +366,7 @@ var Magnifier = class Magnifier {
/**
* getCrosshairsColor:
* Get the color of the crosshairs.
- * @return: The color as a string, e.g. '#0000ffff' or 'blue'.
+ * @returns {string} The color as a string, e.g. '#0000ffff' or 'blue'.
*/
getCrosshairsColor() {
if (this._crossHairs) {
@@ -380,8 +380,8 @@ var Magnifier = class Magnifier {
/**
* setCrosshairsThickness:
* Set the crosshairs thickness for all ZoomRegions.
- * @thickness: The width of the vertical and horizontal lines of the
- * crosshairs.
+ * @param {number} thickness: The width of the vertical and
+ * horizontal lines of the crosshairs.
*/
setCrosshairsThickness(thickness) {
if (this._crossHairs)
@@ -391,8 +391,8 @@ var Magnifier = class Magnifier {
/**
* getCrosshairsThickness:
* Get the crosshairs thickness.
- * @return: The width of the vertical and horizontal lines of the
- * crosshairs.
+ * @returns {number} The width of the vertical and horizontal
+ * lines of the crosshairs.
*/
getCrosshairsThickness() {
if (this._crossHairs)
@@ -403,7 +403,8 @@ var Magnifier = class Magnifier {
/**
* setCrosshairsOpacity:
- * @opacity: Value between 0.0 (transparent) and 1.0 (fully opaque).
+ * @param {number} opacity: Value between 0.0 (transparent)
+ * and 1.0 (fully opaque).
*/
setCrosshairsOpacity(opacity) {
if (this._crossHairs)
@@ -412,7 +413,7 @@ var Magnifier = class Magnifier {
/**
* getCrosshairsOpacity:
- * @return: Value between 0.0 (transparent) and 1.0 (fully opaque).
+ * @returns {number} Value between 0.0 (transparent) and 1.0 (fully opaque).
*/
getCrosshairsOpacity() {
if (this._crossHairs)
@@ -424,8 +425,8 @@ var Magnifier = class Magnifier {
/**
* setCrosshairsLength:
* Set the crosshairs length for all ZoomRegions.
- * @length: The length of the vertical and horizontal lines making up the
- * crosshairs.
+ * @param {number} length: The length of the vertical and horizontal
+ * lines making up the crosshairs.
*/
setCrosshairsLength(length) {
if (this._crossHairs)
@@ -435,8 +436,8 @@ var Magnifier = class Magnifier {
/**
* getCrosshairsLength:
* Get the crosshairs length.
- * @return: The length of the vertical and horizontal lines making up the
- * crosshairs.
+ * @returns {number} The length of the vertical and horizontal
+ * lines making up the crosshairs.
*/
getCrosshairsLength() {
if (this._crossHairs)
@@ -448,7 +449,7 @@ var Magnifier = class Magnifier {
/**
* setCrosshairsClip:
* Set whether the crosshairs are clipped at their intersection.
- * @clip: Flag to indicate whether to clip the crosshairs.
+ * @param {bool} clip: Flag to indicate whether to clip the crosshairs.
*/
setCrosshairsClip(clip) {
if (!this._crossHairs)
@@ -461,7 +462,7 @@ var Magnifier = class Magnifier {
/**
* getCrosshairsClip:
* Get whether the crosshairs are clipped by the mouse image.
- * @return: Whether the crosshairs are clipped.
+ * @returns {bool} Whether the crosshairs are clipped.
*/
getCrosshairsClip() {
if (this._crossHairs) {
@@ -818,7 +819,7 @@ var ZoomRegion = class ZoomRegion {
/**
* setActive:
- * @activate: Boolean to show/hide the ZoomRegion.
+ * @param {bool} activate: Boolean to show/hide the ZoomRegion.
*/
setActive(activate) {
if (activate == this.isActive())
@@ -844,7 +845,7 @@ var ZoomRegion = class ZoomRegion {
/**
* isActive:
- * @return Whether this ZoomRegion is active (boolean).
+ * @returns {bool} Whether this ZoomRegion is active
*/
isActive() {
return this._magView != null;
@@ -852,11 +853,11 @@ var ZoomRegion = class ZoomRegion {
/**
* setMagFactor:
- * @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.
- * @yMagFactor: The power to set the vertical magnification factor to
- * of the magnified view.
+ * @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
+ * magnification factor to of the magnified view.
*/
setMagFactor(xMagFactor, yMagFactor) {
this._changeROI({ xMagFactor,
@@ -866,10 +867,10 @@ var ZoomRegion = class ZoomRegion {
/**
* getMagFactor:
- * @return 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 are doubled
- * in size, and so on.
+ * @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
+ * are doubled in size, and so on.
*/
getMagFactor() {
return [this._xMagFactor, this._yMagFactor];
@@ -877,7 +878,7 @@ var ZoomRegion = class ZoomRegion {
/**
* setMouseTrackingMode
- * @mode: One of the enum MouseTrackingMode values.
+ * @param {GDesktopEnums.MagnifierMouseTrackingMode} mode: the new mode
*/
setMouseTrackingMode(mode) {
if (mode >= GDesktopEnums.MagnifierMouseTrackingMode.NONE &&
@@ -887,7 +888,7 @@ var ZoomRegion = class ZoomRegion {
/**
* getMouseTrackingMode
- * @return: One of the enum MouseTrackingMode values.
+ * @returns {GDesktopEnums.MagnifierMouseTrackingMode} the current mode
*/
getMouseTrackingMode() {
return this._mouseTrackingMode;
@@ -895,7 +896,7 @@ var ZoomRegion = class ZoomRegion {
/**
* setFocusTrackingMode
- * @mode: One of the enum FocusTrackingMode values.
+ * @param {GDesktopEnums.MagnifierFocusTrackingMode} mode: the new mode
*/
setFocusTrackingMode(mode) {
this._focusTrackingMode = mode;
@@ -904,7 +905,7 @@ var ZoomRegion = class ZoomRegion {
/**
* setCaretTrackingMode
- * @mode: One of the enum CaretTrackingMode values.
+ * @param {GDesktopEnums.MagnifierCaretTrackingMode} mode: the new mode
*/
setCaretTrackingMode(mode) {
this._caretTrackingMode = mode;
@@ -934,9 +935,9 @@ var ZoomRegion = class ZoomRegion {
/**
* setViewPort
* Sets the position and size of the ZoomRegion on screen.
- * @viewPort: Object defining the position and size of the view port.
- * It has members x, y, width, height. The values are in
- * stage coordinate space.
+ * @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.
*/
setViewPort(viewPort) {
this._setViewPort(viewPort);
@@ -946,9 +947,9 @@ var ZoomRegion = class ZoomRegion {
/**
* setROI
* Sets the "region of interest" that the ZoomRegion is magnifying.
- * @roi: Object that defines the region of the screen to magnify. It
- * has members x, y, width, height. The values are in
- * screen (unmagnified) coordinate space.
+ * @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.
*/
setROI(roi) {
if (roi.width <= 0 || roi.height <= 0)
@@ -966,8 +967,8 @@ 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.
- * @return an array, [x, y, width, height], representing the bounding
- * rectangle of what is shown in the magnified view.
+ * @returns {number[]} an array, [x, y, width, height], representing
+ * the bounding rectangle of what is shown in the magnified view.
*/
getROI() {
let roiWidth = this._viewPortWidth / this._xMagFactor;
@@ -982,7 +983,7 @@ 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.
- * @lensMode: A boolean to set the sense of lens mode.
+ * @param {bool} lensMode: Whether lensMode should be active
*/
setLensMode(lensMode) {
this._lensMode = lensMode;
@@ -993,7 +994,7 @@ var ZoomRegion = class ZoomRegion {
/**
* isLensMode:
* Is lens mode on or off?
- * @return The lens mode state as a boolean.
+ * @returns {bool} The lens mode state.
*/
isLensMode() {
return this._lensMode;
@@ -1003,7 +1004,7 @@ var ZoomRegion = class ZoomRegion {
* setClampScrollingAtEdges:
* Stop vs. allow scrolling of the magnified contents when it scroll beyond
* the edges of the screen.
- * @clamp: Boolean to turn on/off clamping.
+ * @param {bool} clamp: Boolean to turn on/off clamping.
*/
setClampScrollingAtEdges(clamp) {
this._clampScrollingAtEdges = clamp;
@@ -1087,9 +1088,7 @@ var ZoomRegion = class ZoomRegion {
* setScreenPosition:
* Positions the zoom region to one of the enumerated positions on the
* screen.
- * @position: one of Magnifier.FULL_SCREEN, Magnifier.TOP_HALF,
- * Magnifier.BOTTOM_HALF,Magnifier.LEFT_HALF, or
- * Magnifier.RIGHT_HALF.
+ * @param {GDesktopEnums.MagnifierScreenPosition} inPosition: the position
*/
setScreenPosition(inPosition) {
switch (inPosition) {
@@ -1115,7 +1114,7 @@ var ZoomRegion = class ZoomRegion {
* getScreenPosition:
* Tell the outside world what the current mode is -- magnifiying the
* top half, bottom half, etc.
- * @return: the current mode.
+ * @returns {GDesktopEnums.MagnifierScreenPosition}: the current position.
*/
getScreenPosition() {
return this._screenPosition;
@@ -1124,7 +1123,8 @@ var ZoomRegion = class ZoomRegion {
/**
* scrollToMousePos:
* Set the region of interest based on the position of the system pointer.
- * @return: Whether the system mouse pointer is over the magnified view.
+ * @returns {bool}: Whether the system mouse pointer is over the
+ * magnified view.
*/
scrollToMousePos() {
this._followingCursor = true;
@@ -1161,8 +1161,8 @@ var ZoomRegion = class ZoomRegion {
* scrollContentsTo:
* Shift the contents of the magnified view such it is centered on the given
* coordinate.
- * @x: The x-coord of the point to center on.
- * @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) {
this._clearScrollContentsTimer();
@@ -1175,7 +1175,7 @@ var ZoomRegion = class ZoomRegion {
/**
* addCrosshairs:
* Add crosshairs centered on the magnified mouse.
- * @crossHairs: Crosshairs instance
+ * @param {Crosshairs} crossHairs: Crosshairs instance
*/
addCrosshairs(crossHairs) {
this._crossHairs = crossHairs;
@@ -1189,7 +1189,7 @@ var ZoomRegion = class ZoomRegion {
/**
* setInvertLightness:
* Set whether to invert the lightness of the magnified view.
- * @flag Boolean to either invert brightness (true), or not (false).
+ * @param {bool} flag: whether brightness should be inverted
*/
setInvertLightness(flag) {
this._invertLightness = flag;
@@ -1200,7 +1200,7 @@ var ZoomRegion = class ZoomRegion {
/**
* getInvertLightness:
* Retrieve whether the lightness is inverted.
- * @return Boolean indicating inversion (true), or not (false).
+ * @returns {bool} whether brightness should be inverted
*/
getInvertLightness() {
return this._invertLightness;
@@ -1209,9 +1209,9 @@ var ZoomRegion = class ZoomRegion {
/**
* setColorSaturation:
* Set the color saturation of the magnified view.
- * @sauration 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.
+ * @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.
*/
setColorSaturation(saturation) {
this._colorSaturation = saturation;
@@ -1222,6 +1222,7 @@ var ZoomRegion = class ZoomRegion {
/**
* getColorSaturation:
* Retrieve the color saturation of the magnified view.
+ * @returns {number} the color saturation
*/
getColorSaturation() {
return this._colorSaturation;
@@ -1230,10 +1231,14 @@ var ZoomRegion = class ZoomRegion {
/**
* setBrightness:
* Alter the brightness of the magnified view.
- * @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.
+ * @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.
+ *
+ * {number} brightness.r - the red component
+ * {number} brightness.g - the green component
+ * {number} brightness.b - the blue component
*/
setBrightness(brightness) {
this._brightness.r = brightness.r;
@@ -1246,10 +1251,14 @@ var ZoomRegion = class ZoomRegion {
/**
* setContrast:
* Alter the contrast of the magnified view.
- * @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.
+ * @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.
+ *
+ * {number} contrast.r - the red component
+ * {number} contrast.g - the green component
+ * {number} contrast.b - the blue component
*/
setContrast(contrast) {
this._contrast.r = contrast.r;
@@ -1262,8 +1271,8 @@ var ZoomRegion = class ZoomRegion {
/**
* getContrast:
* Retrieve the contrast of the magnified view.
- * @return Object containing the contrast for the red, green,
- * and blue channels.
+ * @returns {{r: number, g: number, b: number}}: Object containing
+ * the contrast for the red, green, and blue channels.
*/
getContrast() {
let contrast = {};
@@ -1627,11 +1636,12 @@ 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.
- * @zoomRegion: The container to add the crosshairs group to.
- * @magnifiedMouse: The mouse actor for the zoom region -- used to
- * position the crosshairs and properly layer them below
- * the mouse.
- * @return The crosshairs actor, or its clone.
+ * @param {ZoomRegion} zoomRegion: The container to add the crosshairs
+ * group to.
+ * @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.
*/
addToZoomRegion(zoomRegion, magnifiedMouse) {
let crosshairsActor = null;
@@ -1660,7 +1670,8 @@ class Crosshairs extends Clutter.Actor {
/**
* removeFromParent:
- * @childActor: the actor returned from addToZoomRegion
+ * @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.
*/
@@ -1674,7 +1685,7 @@ class Crosshairs extends Clutter.Actor {
/**
* setColor:
* Set the color of the crosshairs.
- * @clutterColor: The color as a Clutter.Color.
+ * @param {Clutter.Color} clutterColor: The color
*/
setColor(clutterColor) {
this._horizLeftHair.background_color = clutterColor;
@@ -1686,7 +1697,7 @@ class Crosshairs extends Clutter.Actor {
/**
* getColor:
* Get the color of the crosshairs.
- * @color: The color as a Clutter.Color.
+ * @returns {ClutterColor} the crosshairs color
*/
getColor() {
return this._horizLeftHair.get_color();
@@ -1695,7 +1706,7 @@ class Crosshairs extends Clutter.Actor {
/**
* setThickness:
* Set the width of the vertical and horizontal lines of the crosshairs.
- * @thickness
+ * @param {number} thickness: the new thickness value
*/
setThickness(thickness) {
this._horizLeftHair.set_height(thickness);
@@ -1708,7 +1719,7 @@ class Crosshairs extends Clutter.Actor {
/**
* getThickness:
* Get the width of the vertical and horizontal lines of the crosshairs.
- * @return: The thickness of the crosshairs.
+ * @returns {number} The thickness of the crosshairs.
*/
getThickness() {
return this._horizLeftHair.get_height();
@@ -1717,7 +1728,8 @@ class Crosshairs extends Clutter.Actor {
/**
* setOpacity:
* Set how opaque the crosshairs are.
- * @opacity: Value between 0 (fully transparent) and 255 (full opaque).
+ * @param {number} opacity: Value between 0 (fully transparent)
+ * and 255 (full opaque).
*/
setOpacity(opacity) {
// set_opacity() throws an exception for values outside the range
@@ -1736,7 +1748,7 @@ class Crosshairs extends Clutter.Actor {
/**
* setLength:
* Set the length of the vertical and horizontal lines in the crosshairs.
- * @length: The length of the crosshairs.
+ * @param {number} length: The length of the crosshairs.
*/
setLength(length) {
this._horizLeftHair.set_width(length);
@@ -1749,7 +1761,7 @@ class Crosshairs extends Clutter.Actor {
/**
* getLength:
* Get the length of the vertical and horizontal lines in the crosshairs.
- * @return: The length of the crosshairs.
+ * @returns {number} The length of the crosshairs.
*/
getLength() {
return this._horizLeftHair.get_width();
@@ -1759,8 +1771,8 @@ class Crosshairs extends Clutter.Actor {
* setClip:
* Set the width and height of the rectangle that clips the crosshairs at
* their intersection
- * @size: Array of [width, height] defining the size of the clip
- * rectangle.
+ * @param {number[]} size: Array of [width, height] defining the size
+ * of the clip rectangle.
*/
setClip(size) {
if (size) {
@@ -1780,7 +1792,7 @@ 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.
- * @clipSize: Optional. If present, an array of the form [width, height].
+ * @param {number[]=} clipSize: If present, the clip's [width, height].
*/
reCenter(clipSize) {
let [groupWidth, groupHeight] = this.get_size();
@@ -1838,7 +1850,7 @@ var MagShaderEffects = class MagShaderEffects {
/**
* setInvertLightness:
* Enable/disable invert lightness effect.
- * @invertFlag: Enabled flag.
+ * @param {bool} invertFlag: Enabled flag.
*/
setInvertLightness(invertFlag) {
this._inverse.set_enabled(invertFlag);
@@ -1851,11 +1863,14 @@ var MagShaderEffects = class MagShaderEffects {
/**
* setBrightness:
* Set the brightness of the magnified view.
- * @brightness: Object containing the brightness 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.
+ * @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.
+ *
+ * {number} brightness.r - the red component
+ * {number} brightness.g - the green component
+ * {number} brightness.b - the blue component
*/
setBrightness(brightness) {
let bRed = brightness.r;
@@ -1874,10 +1889,14 @@ var MagShaderEffects = class MagShaderEffects {
/**
* Set the contrast of the magnified view.
- * @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.
+ * @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.
+ *
+ * {number} contrast.r - the red component
+ * {number} contrast.g - the green component
+ * {number} contrast.b - the blue component
*/
setContrast(contrast) {
let cRed = contrast.r;
diff --git a/js/ui/magnifierDBus.js b/js/ui/magnifierDBus.js
index b797d2bcc8..6f962d13a9 100644
--- a/js/ui/magnifierDBus.js
+++ b/js/ui/magnifierDBus.js
@@ -32,7 +32,7 @@ var ShellMagnifier = class ShellMagnifier {
/**
* setActive:
- * @activate: Boolean to activate or de-activate the magnifier.
+ * @param {bool} activate: activate or de-activate the magnifier.
*/
setActive(activate) {
Main.magnifier.setActive(activate);
@@ -40,7 +40,7 @@ var ShellMagnifier = class ShellMagnifier {
/**
* isActive:
- * @return Whether the magnifier is active (boolean).
+ * @returns {bool} Whether the magnifier is active.
*/
isActive() {
return Main.magnifier.isActive();
@@ -65,22 +65,25 @@ var ShellMagnifier = class ShellMagnifier {
/**
* createZoomRegion:
* Create a new ZoomRegion and return its object path.
- * @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.
- * @yMagFactor: The power to set the vertical magnification of the
- * ZoomRegion.
- * @roi Array of integers defining the region of the
- * screen/desktop to magnify. The array has the form
- * [left, top, right, bottom].
- * @viewPort Array of integers, [left, top, right, bottom] that defines
- * the position of the ZoomRegion on screen.
+ * @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:
+ * The power to set the vertical magnification of the
+ * ZoomRegion.
+ * @param {number[]} roi
+ * Array of integers defining the region of the screen/desktop
+ * to magnify. The array has the form [left, top, right, bottom].
+ * @param {number[]} viewPort
+ * Array of integers, [left, top, right, bottom] that defines
+ * the position of the ZoomRegion on screen.
*
* FIXME: The arguments here are redundant, since the width and height of
* the ROI are determined by the viewport and magnification factors.
* We ignore the passed in width and height.
*
- * @return The newly created ZoomRegion.
+ * @returns {ZoomRegion} The newly created ZoomRegion.
*/
createZoomRegion(xMagFactor, yMagFactor, roi, viewPort) {
let ROI = { x: roi[0], y: roi[1], width: roi[2] - roi[0], height: roi[3] - roi[1] };
@@ -100,7 +103,9 @@ var ShellMagnifier = class ShellMagnifier {
/**
* addZoomRegion:
* Append the given ZoomRegion to the magnifier's list of ZoomRegions.
- * @zoomerObjectPath: The object path for the zoom region proxy.
+ * @param {string} zoomerObjectPath: The object path for the zoom
+ * region proxy.
+ * @returns {bool} whether the region was added successfully
*/
addZoomRegion(zoomerObjectPath) {
let proxyAndZoomRegion = this._zoomers[zoomerObjectPath];
@@ -115,8 +120,8 @@ var ShellMagnifier = class ShellMagnifier {
/**
* getZoomRegions:
* Return a list of ZoomRegion object paths for this Magnifier.
- * @return: The Magnifier's zoom region list as an array of DBus object
- * paths.
+ * @returns {string[]}: The Magnifier's zoom region list as an array
+ * of DBus object paths.
*/
getZoomRegions() {
// There may be more ZoomRegions in the magnifier itself than have
@@ -169,7 +174,7 @@ var ShellMagnifier = class ShellMagnifier {
/**
* fullScreenCapable:
* Consult if the Magnifier can magnify in full-screen mode.
- * @return Always return true.
+ * @returns {bool} Always return true.
*/
fullScreenCapable() {
return true;
@@ -178,7 +183,7 @@ var ShellMagnifier = class ShellMagnifier {
/**
* setCrosswireSize:
* Set the crosswire size of all ZoomRegions.
- * @size: The thickness of each line in the cross wire.
+ * @param {number} size: The thickness of each line in the cross wire.
*/
setCrosswireSize(size) {
Main.magnifier.setCrosshairsThickness(size);
@@ -187,7 +192,7 @@ var ShellMagnifier = class ShellMagnifier {
/**
* getCrosswireSize:
* Get the crosswire size of all ZoomRegions.
- * @return: The thickness of each line in the cross wire.
+ * @returns {number}: The thickness of each line in the cross wire.
*/
getCrosswireSize() {
return Main.magnifier.getCrosshairsThickness();
@@ -196,16 +201,16 @@ var ShellMagnifier = class ShellMagnifier {
/**
* setCrosswireLength:
* Set the crosswire length of all zoom-regions..
- * @size: The length of each line in the cross wire.
+ * @param {number} length: The length of each line in the cross wire.
*/
setCrosswireLength(length) {
Main.magnifier.setCrosshairsLength(length);
}
/**
- * setCrosswireSize:
- * Set the crosswire size of all zoom-regions.
- * @size: The thickness of each line in the cross wire.
+ * getCrosswireSize:
+ * Get the crosswire length of all zoom-regions.
+ * @returns {number} size: The length of each line in the cross wire.
*/
getCrosswireLength() {
return Main.magnifier.getCrosshairsLength();
@@ -214,7 +219,7 @@ var ShellMagnifier = class ShellMagnifier {
/**
* setCrosswireClip:
* Set if the crosswire will be clipped by the cursor image..
- * @clip: Flag to indicate whether to clip the crosswire.
+ * @param {bool} clip: Flag to indicate whether to clip the crosswire.
*/
setCrosswireClip(clip) {
Main.magnifier.setCrosshairsClip(clip);
@@ -223,7 +228,7 @@ var ShellMagnifier = class ShellMagnifier {
/**
* getCrosswireClip:
* Get the crosswire clip value.
- * @return: Whether the crosswire is clipped by the cursor image.
+ * @returns {bool}: Whether the crosswire is clipped by the cursor image.
*/
getCrosswireClip() {
return Main.magnifier.getCrosshairsClip();
@@ -232,7 +237,7 @@ var ShellMagnifier = class ShellMagnifier {
/**
* setCrosswireColor:
* Set the crosswire color of all ZoomRegions.
- * @color: Unsigned int of the form rrggbbaa.
+ * @param {number} color: Unsigned int of the form rrggbbaa.
*/
setCrosswireColor(color) {
Main.magnifier.setCrosshairsColor('#%08x'.format(color));
@@ -241,7 +246,8 @@ var ShellMagnifier = class ShellMagnifier {
/**
* getCrosswireClip:
* Get the crosswire color of all ZoomRegions.
- * @return: The crosswire color as an unsigned int in the form rrggbbaa.
+ * @returns {number}: The crosswire color as an unsigned int in
+ * the form rrggbbaa.
*/
getCrosswireColor() {
let colorString = Main.magnifier.getCrosshairsColor();
@@ -266,11 +272,11 @@ var ShellMagnifierZoomRegion = class ShellMagnifierZoomRegion {
/**
* setMagFactor:
- * @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.
- * @yMagFactor: The power to set the vertical magnification factor to
- * of the magnified view.
+ * @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
+ * magnification factor to of the magnified view.
*/
setMagFactor(xMagFactor, yMagFactor) {
this._zoomRegion.setMagFactor(xMagFactor, yMagFactor);
@@ -278,7 +284,7 @@ var ShellMagnifierZoomRegion = class ShellMagnifierZoomRegion {
/**
* getMagFactor:
- * @return an array, [xMagFactor, yMagFactor], containing the horizontal
+ * @returns {number[]}: [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 are doubled
* in size, and so on.
@@ -290,9 +296,9 @@ var ShellMagnifierZoomRegion = class ShellMagnifierZoomRegion {
/**
* setRoi:
* Sets the "region of interest" that the ZoomRegion is magnifying.
- * @roi Array, [left, top, right, bottom], defining the region of the
- * screen to magnify. The values are in screen (unmagnified)
- * coordinate space.
+ * @param {number[]} roi: [left, top, right, bottom], defining the
+ * region of the screen to magnify.
+ * The values are in screen (unmagnified) coordinate space.
*/
setRoi(roi) {
let roiObject = { x: roi[0], y: roi[1], width: roi[2] - roi[0], height: roi[3] - roi[1] };
@@ -304,7 +310,7 @@ var ShellMagnifierZoomRegion = class ShellMagnifierZoomRegion {
* 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.
- * @return an array, [left, top, right, bottom], representing the bounding
+ * @returns {Array}: [left, top, right, bottom], representing the bounding
* rectangle of what is shown in the magnified view.
*/
getRoi() {
@@ -317,10 +323,11 @@ var ShellMagnifierZoomRegion = class ShellMagnifierZoomRegion {
/**
* Set the "region of interest" by centering the given screen coordinate
* within the zoom region.
- * @x The x-coord of the point to place at the center of the zoom region.
- * @y The y-coord.
- * @return Whether the shift was successful (for GS-mag, this is always
- * true).
+ * @param {number} x: The x-coord of the point to place at the
+ * center of the zoom region.
+ * @param {number} y: The y-coord.
+ * @returns {bool} Whether the shift was successful (for GS-mag, this
+ * is always true).
*/
shiftContentsTo(x, y) {
this._zoomRegion.scrollContentsTo(x, y);
@@ -330,8 +337,8 @@ var ShellMagnifierZoomRegion = class ShellMagnifierZoomRegion {
/**
* moveResize
* Sets the position and size of the ZoomRegion on screen.
- * @viewPort Array, [left, top, right, bottom], defining the position and
- * size on screen to place the zoom region.
+ * @param {number[]} viewPort: [left, top, right, bottom], defining
+ * the position and size on screen to place the zoom region.
*/
moveResize(viewPort) {
let viewRect = { x: viewPort[0], y: viewPort[1], width: viewPort[2] - viewPort[0], height:
viewPort[3] - viewPort[1] };
diff --git a/js/ui/main.js b/js/ui/main.js
index 8419fd436a..09b0249aa7 100644
--- a/js/ui/main.js
+++ b/js/ui/main.js
@@ -337,7 +337,7 @@ function _loadDefaultStylesheet() {
*
* Get the theme CSS file that the shell will load
*
- * Returns: A #GFile that contains the theme CSS,
+ * @returns {?Gio.File}: A #GFile that contains the theme CSS,
* null if using the default
*/
function getThemeStylesheet() {
@@ -346,8 +346,8 @@ function getThemeStylesheet() {
/**
* setThemeStylesheet:
- * @cssStylesheet: A file path that contains the theme CSS,
- * set it to null to use the default
+ * @param {string=} cssStylesheet: A file path that contains the theme CSS,
+ * set it to null to use the default
*
* Set the theme CSS file that the shell will load
*/
@@ -397,8 +397,8 @@ function loadTheme() {
/**
* notify:
- * @msg: A message
- * @details: Additional information
+ * @param {string} msg: A message
+ * @param {string} details: Additional information
*/
function notify(msg, details) {
let source = new MessageTray.SystemNotificationSource();
@@ -410,8 +410,8 @@ function notify(msg, details) {
/**
* notifyError:
- * @msg: An error message
- * @details: Additional information
+ * @param {string} msg: An error message
+ * @param {string} details: Additional information
*
* See shell_global_notify_problem().
*/
@@ -435,8 +435,8 @@ function _findModal(actor) {
/**
* pushModal:
- * @actor: #ClutterActor which will be given keyboard focus
- * @params: optional parameters
+ * @param {Clutter.Actor} actor: actor which will be given keyboard focus
+ * @param {Object=} params: optional parameters
*
* Ensure we are in a mode where all keyboard and mouse input goes to
* the stage, and focus @actor. Multiple calls to this function act in
@@ -459,7 +459,7 @@ function _findModal(actor) {
* global keybindings; the default of NONE will filter
* out all keybindings
*
- * Returns: true iff we successfully acquired a grab or already had one
+ * @returns {bool}: true iff we successfully acquired a grab or already had one
*/
function pushModal(actor, params) {
params = Params.parse(params, { timestamp: global.get_current_time(),
@@ -503,8 +503,9 @@ function pushModal(actor, params) {
/**
* popModal:
- * @actor: #ClutterActor passed to original invocation of pushModal()
- * @timestamp: optional timestamp
+ * @param {Clutter.Actor} actor: the actor passed to original invocation
+ * of pushModal()
+ * @param {number=} timestamp: optional timestamp
*
* Reverse the effect of pushModal(). If this invocation is undoing
* the topmost invocation, then the focus will be restored to the
@@ -590,9 +591,9 @@ function openRunDialog() {
/**
* activateWindow:
- * @window: the Meta.Window to activate
- * @time: (optional) current event time
- * @workspaceNum: (optional) 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
@@ -668,8 +669,8 @@ function _queueBeforeRedraw(workId) {
/**
* initializeDeferredWork:
- * @actor: A #ClutterActor
- * @callback: Function to invoke to perform work
+ * @param {Clutter.Actor} actor: an actor
+ * @param {callback} callback: Function to invoke to perform work
*
* This function sets up a callback to be invoked when either the
* given actor is mapped, or after some period of time when the machine
@@ -682,7 +683,7 @@ function _queueBeforeRedraw(workId) {
* initialization as well, under the assumption that new actors
* will need it.
*
- * Returns: A string work identifier
+ * @returns {string}: A string work identifier
*/
function initializeDeferredWork(actor, callback) {
// Turn into a string so we can use as an object property
@@ -706,7 +707,7 @@ function initializeDeferredWork(actor, callback) {
/**
* queueDeferredWork:
- * @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/popupMenu.js b/js/ui/popupMenu.js
index acd89265e4..53a1cd1704 100644
--- a/js/ui/popupMenu.js
+++ b/js/ui/popupMenu.js
@@ -27,7 +27,9 @@ function isPopupMenuItemVisible(child) {
}
/**
- * @side Side to which the arrow points.
+ * arrowIcon
+ * @param {St.Side} side - Side to which the arrow points.
+ * @returns {St.Icon} a new arrow icon
*/
function arrowIcon(side) {
let iconName;
diff --git a/js/ui/scripting.js b/js/ui/scripting.js
index 5b71376033..ee775e4f01 100644
--- a/js/ui/scripting.js
+++ b/js/ui/scripting.js
@@ -32,7 +32,8 @@ const { loadInterfaceXML } = imports.misc.fileUtils;
/**
* sleep:
- * @milliseconds: number of milliseconds to wait
+ * @param {number} milliseconds - number of milliseconds to wait
+ * @returns {Promise} that resolves after @milliseconds ms
*
* Used within an automation script to pause the the execution of the
* current script for the specified amount of time. Use as
@@ -50,6 +51,7 @@ function sleep(milliseconds) {
/**
* waitLeisure:
+ * @returns {Promise} that resolves when the shell is idle
*
* Used within an automation script to pause the the execution of the
* current script until the shell is completely idle. Use as
@@ -90,13 +92,13 @@ function _callRemote(obj, method, ...args) {
/**
* createTestWindow:
- * @params: options for window creation.
- * width - width of window, in pixels (default 640)
- * height - height of window, in pixels (default 480)
- * alpha - whether the window should have an alpha channel (default false)
- * maximized - whether the window should be created maximized (default false)
- * redraws - whether the window should continually redraw itself (default false)
- * @maximized: whethe the window should be created maximized
+ * @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
+ * @returns {Promise}
*
* Creates a window using gnome-shell-perf-helper for testing purposes.
* While this function can be used with yield in an automation
@@ -119,6 +121,7 @@ function createTestWindow(params) {
/**
* waitTestWindows:
+ * @returns {Promise}
*
* Used within an automation script to pause until all windows previously
* created with createTestWindow have been mapped and exposed.
@@ -130,6 +133,7 @@ function waitTestWindows() {
/**
* destroyTestWindows:
+ * @returns {Promise}
*
* Destroys all windows previously created with createTestWindow().
* While this function can be used with yield in an automation
@@ -144,8 +148,8 @@ function destroyTestWindows() {
/**
* defineScriptEvent
- * @name: The event will be called script.<name>
- * @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
@@ -159,7 +163,7 @@ function defineScriptEvent(name, description) {
/**
* scriptEvent
- * @name: Name registered with defineScriptEvent()
+ * @param {string} name: Name registered with defineScriptEvent()
*
* Convenience function to record a script-local performance event
* previously defined with defineScriptEvent
@@ -274,8 +278,9 @@ function _collect(scriptModule, outputFile) {
/**
* runPerfScript
- * @scriptModule: module object with run and finish functions
- * and event handlers
+ * @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.
diff --git a/js/ui/shellDBus.js b/js/ui/shellDBus.js
index 8b3db8fc0e..22d9e65e9b 100644
--- a/js/ui/shellDBus.js
+++ b/js/ui/shellDBus.js
@@ -39,7 +39,8 @@ var GnomeShell = class {
/**
* Eval:
- * @code: A string containing JavaScript code
+ * @param {string} code: A string containing JavaScript code
+ * @returns {Array}
*
* This function executes arbitrary code in the main
* loop, and returns a boolean success and
diff --git a/js/ui/shellMountOperation.js b/js/ui/shellMountOperation.js
index 61dc9171e7..4934ee4266 100644
--- a/js/ui/shellMountOperation.js
+++ b/js/ui/shellMountOperation.js
@@ -618,18 +618,22 @@ var GnomeShellMountOpHandler = class {
/**
* AskPassword:
- * @id: an opaque ID identifying the object for which the operation is requested
- * The ID must be unique in the context of the calling process.
- * @message: the message to display
- * @icon_name: the name of an icon to display
- * @default_user: the default username for display
- * @default_domain: the default domain for display
- * @flags: a set of GAskPasswordFlags
- * @response: a GMountOperationResult
- * @response_details: a dictionary containing the response details as
- * entered by the user. The dictionary MAY contain the following properties:
+ * @param {Array} params
+ * {string} id: an opaque ID identifying the object for which
+ * the operation is requested
+ * {string} message: the message to display
+ * {string} icon_name: the name of an icon to display
+ * {string} default_user: the default username for display
+ * {string} default_domain: the default domain for display
+ * {Gio.AskPasswordFlags} flags: a set of GAskPasswordFlags
+ * {Gio.MountOperationResults} response: a GMountOperationResult
+ * {Object} response_details: a dictionary containing response details as
+ * entered by the user. The dictionary MAY contain the following
+ * properties:
* - "password" -> (s): a password to be used to complete the mount operation
* - "password_save" -> (u): a GPasswordSave
+ * @param {Gio.DBusMethodInvocation} invocation
+ * The ID must be unique in the context of the calling process.
*
* The dialog will stay visible until clients call the Close() method, or
* another dialog becomes visible.
@@ -673,16 +677,14 @@ var GnomeShellMountOpHandler = class {
/**
* AskQuestion:
- * @id: an opaque ID identifying the object for which the operation is requested
+ * @param {Array} params - params
+ * {string} id: an opaque ID identifying the object for which
+ * the operation is requested
* The ID must be unique in the context of the calling process.
- * @message: the message to display
- * @icon_name: the name of an icon to display
- * @choices: an array of choice strings
- * GetResponse:
- * @response: a GMountOperationResult
- * @response_details: a dictionary containing the response details as
- * entered by the user. The dictionary MAY contain the following properties:
- * - "choice" -> (i): the chosen answer among the array of strings passed in
+ * {string} message: the message to display
+ * {string} icon_name: the name of an icon to display
+ * {string[]} choices: an array of choice strings
+ * @param {Gio.DBusMethodInvocation} invocation - invocation
*
* The dialog will stay visible until clients call the Close() method, or
* another dialog becomes visible.
@@ -711,16 +713,15 @@ var GnomeShellMountOpHandler = class {
/**
* ShowProcesses:
- * @id: an opaque ID identifying the object for which the operation is requested
+ * @param {Array} params - params
+ * {string} id: an opaque ID identifying the object for which
+ * the operation is requested
* The ID must be unique in the context of the calling process.
- * @message: the message to display
- * @icon_name: the name of an icon to display
- * @application_pids: the PIDs of the applications to display
- * @choices: an array of choice strings
- * @response: a GMountOperationResult
- * @response_details: a dictionary containing the response details as
- * entered by the user. The dictionary MAY contain the following properties:
- * - "choice" -> (i): the chosen answer among the array of strings passed in
+ * {string} message: the message to display
+ * {string} icon_name: the name of an icon to display
+ * {number[]} application_pids: the PIDs of the applications to display
+ * {string[]} choices: an array of choice strings
+ * @param {Gio.DBusMethodInvocation} invocation - invocation
*
* The dialog will stay visible until clients call the Close() method, or
* another dialog becomes visible.
@@ -759,6 +760,8 @@ var GnomeShellMountOpHandler = class {
/**
* Close:
+ * @param {Array} _params - params
+ * @param {Gio.DBusMethodInvocation} _invocation - invocation
*
* Closes a dialog previously opened by AskPassword, AskQuestion or ShowProcesses.
* If no dialog is open, does nothing.
[
Date Prev][
Date Next] [
Thread Prev][
Thread Next]
[
Thread Index]
[
Date Index]
[
Author Index]
