brl/gnome-shell
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

cleanup: Use JSDoc for documentation comments

Browse Source 
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
This commit is contained in:
Florian Müllner 2019-10-17 18:41:52 +02:00 committed by Georges Basile Stavracas Neto
parent 077d8f33fb
commit 61210fdae1
14 changed files with 291 additions and 245 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

13
js/misc/extensionUtils.js
View File

@ -36,7 +36,8 @@ const SERIALIZED_PROPERTIES = ['type', 'state', 'path', 'error', 'hasPrefs', 'ca
/** /**
* getCurrentExtension: * 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() { function getCurrentExtension() {
let stack = (new Error()).stack.split('\n'); let stack = (new Error()).stack.split('\n');
@ -84,7 +85,7 @@ function getCurrentExtension() {
/** /**
* initTranslations: * initTranslations:
* @domain: (optional): the gettext domain to use * @param {string=} domain - the gettext domain to use
* *
* Initialize Gettext to load translations from extensionsdir/locale. * Initialize Gettext to load translations from extensionsdir/locale.
* If @domain is not provided, it will be taken from metadata['gettext-domain'] * If @domain is not provided, it will be taken from metadata['gettext-domain']
@ -108,7 +109,8 @@ function initTranslations(domain) {
/** /**
* getSettings: * 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 * Builds and returns a GSettings schema for @schema, using schema files
* in extensionsdir/schemas. If @schema is omitted, it is taken from * in extensionsdir/schemas. If @schema is omitted, it is taken from
@ -145,8 +147,9 @@ function getSettings(schema) {
/** /**
* versionCheck: * versionCheck:
* @required: an array of versions we're compatible with * @param {string[]} required - an array of versions we're compatible with
* @current: the version we have * @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. * Check if a component is compatible for an extension.
* @required is an array, and at least one version must match. * @required is an array, and at least one version must match.

3
js/misc/loginManager.js
View File

@ -74,8 +74,9 @@ function registerSessionWithGDM() {
let _loginManager = null; let _loginManager = null;
/** /**
* LoginManager: * getLoginManager:
* An abstraction over systemd/logind and ConsoleKit. * An abstraction over systemd/logind and ConsoleKit.
* @returns {object} - the LoginManager singleton
* *
*/ */
function getLoginManager() { function getLoginManager() {

6
js/ui/altTab.js
View File

@ -293,9 +293,9 @@ class AppSwitcherPopup extends SwitcherPopup.SwitcherPopup {
/** /**
* _select: * _select:
* @app: index of the app to select * @param {number} app: index of the app to select
* @window: (optional) index of which of @app's windows to select * @param {number=} window: index of which of @app's windows to select
* @forceAppFocus: optional flag, see below * @param {bool} forceAppFocus: optional flag, see below
* *
* Selects the indicated @app, and optional @window, and sets * Selects the indicated @app, and optional @window, and sets
* this._thumbnailsFocused appropriately to indicate whether the * this._thumbnailsFocused appropriately to indicate whether the

30
js/ui/components/telepathyClient.js
View File

@ -656,16 +656,16 @@ var ChatNotification = HAVE_TP ? GObject.registerClass({
/** /**
* appendMessage: * appendMessage:
* @message: An object with the properties: * @param {Object} message: An object with the properties
* text: the body of the message, * {string} message.text: the body of the message,
* messageType: a #Tp.ChannelTextMessageType, * {Tp.ChannelTextMessageType} message.messageType: the type
* sender: the name of the sender, * {string} message.sender: the name of the sender,
* timestamp: the time the message was sent * {number} message.timestamp: the time the message was sent
* direction: a #NotificationDirection * {NotificationDirection} message.direction: a #NotificationDirection
* *
* @noTimestamp: Whether to add a timestamp. If %true, no timestamp * @param {bool} noTimestamp: Whether to add a timestamp. If %true,
* will be added, regardless of the difference since the * no timestamp will be added, regardless of the difference since
* last timestamp * the last timestamp
*/ */
appendMessage(message, noTimestamp) { appendMessage(message, noTimestamp) {
let messageBody = GLib.markup_escape_text(message.text, -1); let messageBody = GLib.markup_escape_text(message.text, -1);
@ -720,13 +720,13 @@ var ChatNotification = HAVE_TP ? GObject.registerClass({
/** /**
* _append: * _append:
* @props: An object with the properties: * @param {Object} props: An object with the properties:
* body: The text of the message. * {string} props.body: The text of the message.
* group: The group of the message, one of: * {string} props.group: The group of the message, one of:
* 'received', 'sent', 'meta'. * 'received', 'sent', 'meta'.
* styles: Style class names for the message to have. * {string[]} props.styles: Style class names for the message to have.
* timestamp: The timestamp of the message. * {number} props.timestamp: The timestamp of the message.
* noTimestamp: suppress timestamp signal? * {bool} props.noTimestamp: suppress timestamp signal?
*/ */
_append(props) { _append(props) {
let currentTime = Date.now() / 1000; let currentTime = Date.now() / 1000;

13
js/ui/dnd.js
View File

@ -292,9 +292,11 @@ var _Draggable = class _Draggable {
/** /**
* startDrag: * startDrag:
* @stageX: X coordinate of event * @param {number} stageX: X coordinate of event
* @stageY: Y coordinate of event * @param {number} stageY: Y coordinate of event
* @time: Event timestamp * @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. * Directly initiate a drag and drop operation from the given actor.
* This function is useful to call if you've specified manualMode * This function is useful to call if you've specified manualMode
@ -746,8 +748,9 @@ Signals.addSignalMethods(_Draggable.prototype);
/** /**
* makeDraggable: * makeDraggable:
* @actor: Source actor * @param {Clutter.Actor} actor: Source actor
* @params: (optional) Additional parameters * @param {Object=} params: Additional parameters
* @returns {Object} a new Draggable
* *
* Create an object which controls drag and drop for the given actor. * Create an object which controls drag and drop for the given actor.
* *

7
js/ui/iconGrid.js
View File

@ -958,9 +958,10 @@ var PaginatedIconGrid = GObject.registerClass({
/** /**
* openExtraSpace: * openExtraSpace:
* @sourceItem: the item for which to create extra space * @param {Clutter.Actor} sourceItem: item for which to create extra space
* @side: where @sourceItem should be located relative to the created space * @param {St.Side} side: where @sourceItem should be located relative to
* @nRows: the amount of space to create * the created space
* @param {number} nRows: the amount of space to create
* *
* Pan view to create extra space for @nRows above or below @sourceItem. * Pan view to create extra space for @nRows above or below @sourceItem.
*/ */

2
js/ui/lightbox.js
View File

@ -245,7 +245,7 @@ var Lightbox = GObject.registerClass({
/** /**
* highlight: * highlight:
* @window: actor to highlight * @param {Clutter.Actor=} window: actor to highlight
* *
* Highlights the indicated actor and unhighlights any other * Highlights the indicated actor and unhighlights any other
* currently-highlighted actor. With no arguments or a false/null * currently-highlighted actor. With no arguments or a false/null

217
js/ui/magnifier.js
View File

@ -141,7 +141,7 @@ var Magnifier = class Magnifier {
/** /**
* setActive: * setActive:
* Show/hide all the zoom regions. * 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) { setActive(activate) {
let isActive = this.isActive(); let isActive = this.isActive();
@ -177,7 +177,7 @@ var Magnifier = class Magnifier {
/** /**
* isActive: * isActive:
* @return Whether the magnifier is active (boolean). * @returns {bool} Whether the magnifier is active.
*/ */
isActive() { isActive() {
// Sufficient to check one ZoomRegion since Magnifier's active // Sufficient to check one ZoomRegion since Magnifier's active
@ -212,7 +212,7 @@ var Magnifier = class Magnifier {
/** /**
* isTrackingMouse: * isTrackingMouse:
* Is the magnifier tracking the mouse currently? * @returns {bool} whether the magnifier is currently tracking the mouse
*/ */
isTrackingMouse() { isTrackingMouse() {
return !!this._mouseTrackingId; return !!this._mouseTrackingId;
@ -222,7 +222,7 @@ var Magnifier = class Magnifier {
* scrollToMousePos: * scrollToMousePos:
* Position all zoom regions' ROI relative to the current location of the * Position all zoom regions' ROI relative to the current location of the
* system pointer. * system pointer.
* @return true. * @returns {bool} true.
*/ */
scrollToMousePos() { scrollToMousePos() {
let [xMouse, yMouse] = global.get_pointer(); let [xMouse, yMouse] = global.get_pointer();
@ -247,17 +247,17 @@ var Magnifier = class Magnifier {
/** /**
* createZoomRegion: * createZoomRegion:
* Create a ZoomRegion instance with the given properties. * Create a ZoomRegion instance with the given properties.
* @xMagFactor: The power to set horizontal magnification of the * @param {number} xMagFactor:
* ZoomRegion. A value of 1.0 means no magnification. A * The power to set horizontal magnification of the ZoomRegion. A value
* value of 2.0 doubles the size. * of 1.0 means no magnification, a value of 2.0 doubles the size.
* @yMagFactor: The power to set the vertical magnification of the * @param {number} yMagFactor:
* ZoomRegion. * The power to set the vertical magnification of the ZoomRegion.
* @roi Object in the form { x, y, width, height } that * @param {{x: number, y: number, width: number, height: number}} roi:
* defines the region to magnify. Given in unmagnified * The reg Object that defines the region to magnify, given in
* coordinates. * unmagnified coordinates.
* @viewPort Object in the form { x, y, width, height } that defines * @param {{x: number, y: number, width: number, height: number}} viewPort:
* the position of the ZoomRegion on screen. * Object that defines the position of the ZoomRegion on screen.
* @return The newly created ZoomRegion. * @returns {ZoomRegion} the newly created ZoomRegion.
*/ */
createZoomRegion(xMagFactor, yMagFactor, roi, viewPort) { createZoomRegion(xMagFactor, yMagFactor, roi, viewPort) {
let zoomRegion = new ZoomRegion(this, this._cursorRoot); let zoomRegion = new ZoomRegion(this, this._cursorRoot);
@ -277,7 +277,7 @@ var Magnifier = class Magnifier {
* addZoomRegion: * addZoomRegion:
* Append the given ZoomRegion to the list of currently defined ZoomRegions * Append the given ZoomRegion to the list of currently defined ZoomRegions
* for this Magnifier instance. * for this Magnifier instance.
* @zoomRegion: The zoomRegion to add. * @param {ZoomRegion} zoomRegion: The zoomRegion to add.
*/ */
addZoomRegion(zoomRegion) { addZoomRegion(zoomRegion) {
if (zoomRegion) { if (zoomRegion) {
@ -290,7 +290,7 @@ var Magnifier = class Magnifier {
/** /**
* getZoomRegions: * getZoomRegions:
* Return a list of ZoomRegion's for this Magnifier. * 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() { getZoomRegions() {
return this._zoomRegions; return this._zoomRegions;
@ -338,7 +338,7 @@ var Magnifier = class Magnifier {
/** /**
* setCrosshairsVisible: * setCrosshairsVisible:
* Show or hide the cross hair. * 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) { setCrosshairsVisible(visible) {
if (visible) { if (visible) {
@ -354,7 +354,7 @@ var Magnifier = class Magnifier {
/** /**
* setCrosshairsColor: * setCrosshairsColor:
* Set the color of the crosshairs for all ZoomRegions. * 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) { setCrosshairsColor(color) {
if (this._crossHairs) { if (this._crossHairs) {
@ -366,7 +366,7 @@ var Magnifier = class Magnifier {
/** /**
* getCrosshairsColor: * getCrosshairsColor:
* Get the color of the crosshairs. * 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() { getCrosshairsColor() {
if (this._crossHairs) { if (this._crossHairs) {
@ -380,8 +380,8 @@ var Magnifier = class Magnifier {
/** /**
* setCrosshairsThickness: * setCrosshairsThickness:
* Set the crosshairs thickness for all ZoomRegions. * Set the crosshairs thickness for all ZoomRegions.
* @thickness: The width of the vertical and horizontal lines of the * @param {number} thickness: The width of the vertical and
* crosshairs. * horizontal lines of the crosshairs.
*/ */
setCrosshairsThickness(thickness) { setCrosshairsThickness(thickness) {
if (this._crossHairs) if (this._crossHairs)
@ -391,8 +391,8 @@ var Magnifier = class Magnifier {
/** /**
* getCrosshairsThickness: * getCrosshairsThickness:
* Get the crosshairs thickness. * Get the crosshairs thickness.
* @return: The width of the vertical and horizontal lines of the * @returns {number} The width of the vertical and horizontal
* crosshairs. * lines of the crosshairs.
*/ */
getCrosshairsThickness() { getCrosshairsThickness() {
if (this._crossHairs) if (this._crossHairs)
@ -403,7 +403,8 @@ var Magnifier = class Magnifier {
/** /**
* setCrosshairsOpacity: * 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) { setCrosshairsOpacity(opacity) {
if (this._crossHairs) if (this._crossHairs)
@ -412,7 +413,7 @@ var Magnifier = class Magnifier {
/** /**
* getCrosshairsOpacity: * 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() { getCrosshairsOpacity() {
if (this._crossHairs) if (this._crossHairs)
@ -424,8 +425,8 @@ var Magnifier = class Magnifier {
/** /**
* setCrosshairsLength: * setCrosshairsLength:
* Set the crosshairs length for all ZoomRegions. * Set the crosshairs length for all ZoomRegions.
* @length: The length of the vertical and horizontal lines making up the * @param {number} length: The length of the vertical and horizontal
* crosshairs. * lines making up the crosshairs.
*/ */
setCrosshairsLength(length) { setCrosshairsLength(length) {
if (this._crossHairs) if (this._crossHairs)
@ -435,8 +436,8 @@ var Magnifier = class Magnifier {
/** /**
* getCrosshairsLength: * getCrosshairsLength:
* Get the crosshairs length. * Get the crosshairs length.
* @return: The length of the vertical and horizontal lines making up the * @returns {number} The length of the vertical and horizontal
* crosshairs. * lines making up the crosshairs.
*/ */
getCrosshairsLength() { getCrosshairsLength() {
if (this._crossHairs) if (this._crossHairs)
@ -448,7 +449,7 @@ var Magnifier = class Magnifier {
/** /**
* setCrosshairsClip: * setCrosshairsClip:
* Set whether the crosshairs are clipped at their intersection. * 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) { setCrosshairsClip(clip) {
if (!this._crossHairs) if (!this._crossHairs)
@ -461,7 +462,7 @@ var Magnifier = class Magnifier {
/** /**
* getCrosshairsClip: * getCrosshairsClip:
* Get whether the crosshairs are clipped by the mouse image. * Get whether the crosshairs are clipped by the mouse image.
* @return: Whether the crosshairs are clipped. * @returns {bool} Whether the crosshairs are clipped.
*/ */
getCrosshairsClip() { getCrosshairsClip() {
if (this._crossHairs) { if (this._crossHairs) {
@ -818,7 +819,7 @@ var ZoomRegion = class ZoomRegion {
/** /**
* setActive: * setActive:
* @activate: Boolean to show/hide the ZoomRegion. * @param {bool} activate: Boolean to show/hide the ZoomRegion.
*/ */
setActive(activate) { setActive(activate) {
if (activate == this.isActive()) if (activate == this.isActive())
@ -844,7 +845,7 @@ var ZoomRegion = class ZoomRegion {
/** /**
* isActive: * isActive:
* @return Whether this ZoomRegion is active (boolean). * @returns {bool} Whether this ZoomRegion is active
*/ */
isActive() { isActive() {
return this._magView != null; return this._magView != null;
@ -852,11 +853,11 @@ var ZoomRegion = class ZoomRegion {
/** /**
* setMagFactor: * setMagFactor:
* @xMagFactor: The power to set the horizontal magnification factor to * @param {number} xMagFactor: The power to set the horizontal
* of the magnified view. A value of 1.0 means no * magnification factor to of the magnified view. A value of 1.0
* magnification. A value of 2.0 doubles the size. * means no magnification. A value of 2.0 doubles the size.
* @yMagFactor: The power to set the vertical magnification factor to * @param {number} yMagFactor: The power to set the vertical
* of the magnified view. * magnification factor to of the magnified view.
*/ */
setMagFactor(xMagFactor, yMagFactor) { setMagFactor(xMagFactor, yMagFactor) {
this._changeROI({ xMagFactor, this._changeROI({ xMagFactor,
@ -866,10 +867,10 @@ var ZoomRegion = class ZoomRegion {
/** /**
* getMagFactor: * getMagFactor:
* @return an array, [xMagFactor, yMagFactor], containing the horizontal * @returns {number[]} an array, [xMagFactor, yMagFactor], containing
* and vertical magnification powers. A value of 1.0 means no * the horizontal and vertical magnification powers. A value of
* magnification. A value of 2.0 means the contents are doubled * 1.0 means no magnification. A value of 2.0 means the contents
* in size, and so on. * are doubled in size, and so on.
*/ */
getMagFactor() { getMagFactor() {
return [this._xMagFactor, this._yMagFactor]; return [this._xMagFactor, this._yMagFactor];
@ -877,7 +878,7 @@ var ZoomRegion = class ZoomRegion {
/** /**
* setMouseTrackingMode * setMouseTrackingMode
* @mode: One of the enum MouseTrackingMode values. * @param {GDesktopEnums.MagnifierMouseTrackingMode} mode: the new mode
*/ */
setMouseTrackingMode(mode) { setMouseTrackingMode(mode) {
if (mode >= GDesktopEnums.MagnifierMouseTrackingMode.NONE && if (mode >= GDesktopEnums.MagnifierMouseTrackingMode.NONE &&
@ -887,7 +888,7 @@ var ZoomRegion = class ZoomRegion {
/** /**
* getMouseTrackingMode * getMouseTrackingMode
* @return: One of the enum MouseTrackingMode values. * @returns {GDesktopEnums.MagnifierMouseTrackingMode} the current mode
*/ */
getMouseTrackingMode() { getMouseTrackingMode() {
return this._mouseTrackingMode; return this._mouseTrackingMode;
@ -895,7 +896,7 @@ var ZoomRegion = class ZoomRegion {
/** /**
* setFocusTrackingMode * setFocusTrackingMode
* @mode: One of the enum FocusTrackingMode values. * @param {GDesktopEnums.MagnifierFocusTrackingMode} mode: the new mode
*/ */
setFocusTrackingMode(mode) { setFocusTrackingMode(mode) {
this._focusTrackingMode = mode; this._focusTrackingMode = mode;
@ -904,7 +905,7 @@ var ZoomRegion = class ZoomRegion {
/** /**
* setCaretTrackingMode * setCaretTrackingMode
* @mode: One of the enum CaretTrackingMode values. * @param {GDesktopEnums.MagnifierCaretTrackingMode} mode: the new mode
*/ */
setCaretTrackingMode(mode) { setCaretTrackingMode(mode) {
this._caretTrackingMode = mode; this._caretTrackingMode = mode;
@ -934,9 +935,9 @@ var ZoomRegion = class ZoomRegion {
/** /**
* setViewPort * setViewPort
* Sets the position and size of the ZoomRegion on screen. * Sets the position and size of the ZoomRegion on screen.
* @viewPort: Object defining the position and size of the view port. * @param {{x: number, y: number, width: number, height: number}} viewPort:
* It has members x, y, width, height. The values are in * Object defining the position and size of the view port.
* stage coordinate space. * The values are in stage coordinate space.
*/ */
setViewPort(viewPort) { setViewPort(viewPort) {
this._setViewPort(viewPort); this._setViewPort(viewPort);
@ -946,9 +947,9 @@ var ZoomRegion = class ZoomRegion {
/** /**
* setROI * setROI
* Sets the "region of interest" that the ZoomRegion is magnifying. * Sets the "region of interest" that the ZoomRegion is magnifying.
* @roi: Object that defines the region of the screen to magnify. It * @param {{x: number, y: number, width: number, height: number}} roi:
* has members x, y, width, height. The values are in * Object that defines the region of the screen to magnify.
* screen (unmagnified) coordinate space. * The values are in screen (unmagnified) coordinate space.
*/ */
setROI(roi) { setROI(roi) {
if (roi.width <= 0 || roi.height <= 0) 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 * Retrieves the "region of interest" -- the rectangular bounds of that part
* of the desktop that the magnified view is showing (x, y, width, height). * of the desktop that the magnified view is showing (x, y, width, height).
* The bounds are given in non-magnified coordinates. * The bounds are given in non-magnified coordinates.
* @return an array, [x, y, width, height], representing the bounding * @returns {number[]} an array, [x, y, width, height], representing
* rectangle of what is shown in the magnified view. * the bounding rectangle of what is shown in the magnified view.
*/ */
getROI() { getROI() {
let roiWidth = this._viewPortWidth / this._xMagFactor; let roiWidth = this._viewPortWidth / this._xMagFactor;
@ -982,7 +983,7 @@ var ZoomRegion = class ZoomRegion {
* setLensMode: * 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. * 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) { setLensMode(lensMode) {
this._lensMode = lensMode; this._lensMode = lensMode;
@ -993,7 +994,7 @@ var ZoomRegion = class ZoomRegion {
/** /**
* isLensMode: * isLensMode:
* Is lens mode on or off? * Is lens mode on or off?
* @return The lens mode state as a boolean. * @returns {bool} The lens mode state.
*/ */
isLensMode() { isLensMode() {
return this._lensMode; return this._lensMode;
@ -1003,7 +1004,7 @@ var ZoomRegion = class ZoomRegion {
* setClampScrollingAtEdges: * setClampScrollingAtEdges:
* Stop vs. allow scrolling of the magnified contents when it scroll beyond * Stop vs. allow scrolling of the magnified contents when it scroll beyond
* the edges of the screen. * the edges of the screen.
* @clamp: Boolean to turn on/off clamping. * @param {bool} clamp: Boolean to turn on/off clamping.
*/ */
setClampScrollingAtEdges(clamp) { setClampScrollingAtEdges(clamp) {
this._clampScrollingAtEdges = clamp; this._clampScrollingAtEdges = clamp;
@ -1087,9 +1088,7 @@ var ZoomRegion = class ZoomRegion {
* setScreenPosition: * setScreenPosition:
* Positions the zoom region to one of the enumerated positions on the * Positions the zoom region to one of the enumerated positions on the
* screen. * screen.
* @position: one of Magnifier.FULL_SCREEN, Magnifier.TOP_HALF, * @param {GDesktopEnums.MagnifierScreenPosition} inPosition: the position
* Magnifier.BOTTOM_HALF,Magnifier.LEFT_HALF, or
* Magnifier.RIGHT_HALF.
*/ */
setScreenPosition(inPosition) { setScreenPosition(inPosition) {
switch (inPosition) { switch (inPosition) {
@ -1115,7 +1114,7 @@ var ZoomRegion = class ZoomRegion {
* getScreenPosition: * getScreenPosition:
* Tell the outside world what the current mode is -- magnifiying the * Tell the outside world what the current mode is -- magnifiying the
* top half, bottom half, etc. * top half, bottom half, etc.
* @return: the current mode. * @returns {GDesktopEnums.MagnifierScreenPosition}: the current position.
*/ */
getScreenPosition() { getScreenPosition() {
return this._screenPosition; return this._screenPosition;
@ -1124,7 +1123,8 @@ var ZoomRegion = class ZoomRegion {
/** /**
* scrollToMousePos: * scrollToMousePos:
* Set the region of interest based on the position of the system pointer. * 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() { scrollToMousePos() {
this._followingCursor = true; this._followingCursor = true;
@ -1161,8 +1161,8 @@ var ZoomRegion = class ZoomRegion {
* scrollContentsTo: * scrollContentsTo:
* Shift the contents of the magnified view such it is centered on the given * Shift the contents of the magnified view such it is centered on the given
* coordinate. * coordinate.
* @x: The x-coord of the point to center on. * @param {number} x: The x-coord of the point to center on.
* @y: The y-coord of the point to center on. * @param {number} y: The y-coord of the point to center on.
*/ */
scrollContentsTo(x, y) { scrollContentsTo(x, y) {
this._clearScrollContentsTimer(); this._clearScrollContentsTimer();
@ -1175,7 +1175,7 @@ var ZoomRegion = class ZoomRegion {
/** /**
* addCrosshairs: * addCrosshairs:
* Add crosshairs centered on the magnified mouse. * Add crosshairs centered on the magnified mouse.
* @crossHairs: Crosshairs instance * @param {Crosshairs} crossHairs: Crosshairs instance
*/ */
addCrosshairs(crossHairs) { addCrosshairs(crossHairs) {
this._crossHairs = crossHairs; this._crossHairs = crossHairs;
@ -1189,7 +1189,7 @@ var ZoomRegion = class ZoomRegion {
/** /**
* setInvertLightness: * setInvertLightness:
* Set whether to invert the lightness of the magnified view. * 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) { setInvertLightness(flag) {
this._invertLightness = flag; this._invertLightness = flag;
@ -1200,7 +1200,7 @@ var ZoomRegion = class ZoomRegion {
/** /**
* getInvertLightness: * getInvertLightness:
* Retrieve whether the lightness is inverted. * Retrieve whether the lightness is inverted.
* @return Boolean indicating inversion (true), or not (false). * @returns {bool} whether brightness should be inverted
*/ */
getInvertLightness() { getInvertLightness() {
return this._invertLightness; return this._invertLightness;
@ -1209,8 +1209,8 @@ var ZoomRegion = class ZoomRegion {
/** /**
* setColorSaturation: * setColorSaturation:
* Set the color saturation of the magnified view. * Set the color saturation of the magnified view.
* @sauration A value from 0.0 to 1.0 that defines the color * @param {number} saturation: A value from 0.0 to 1.0 that defines
* saturation, with 0.0 defining no color (grayscale), * the color saturation, with 0.0 defining no color (grayscale),
* and 1.0 defining full color. * and 1.0 defining full color.
*/ */
setColorSaturation(saturation) { setColorSaturation(saturation) {
@ -1222,6 +1222,7 @@ var ZoomRegion = class ZoomRegion {
/** /**
* getColorSaturation: * getColorSaturation:
* Retrieve the color saturation of the magnified view. * Retrieve the color saturation of the magnified view.
* @returns {number} the color saturation
*/ */
getColorSaturation() { getColorSaturation() {
return this._colorSaturation; return this._colorSaturation;
@ -1230,10 +1231,14 @@ var ZoomRegion = class ZoomRegion {
/** /**
* setBrightness: * setBrightness:
* Alter the brightness of the magnified view. * Alter the brightness of the magnified view.
* @brightness Object containing the contrast for the red, green, * @param {Object} brightness: Object containing the contrast for the
* and blue channels. Values of 0.0 represent "standard" * red, green, and blue channels. Values of 0.0 represent "standard"
* brightness (no change), whereas values less or greater than * brightness (no change), whereas values less or greater than
* 0.0 indicate decreased or incresaed brightness, respectively. * 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) { setBrightness(brightness) {
this._brightness.r = brightness.r; this._brightness.r = brightness.r;
@ -1246,10 +1251,14 @@ var ZoomRegion = class ZoomRegion {
/** /**
* setContrast: * setContrast:
* Alter the contrast of the magnified view. * Alter the contrast of the magnified view.
* @contrast Object containing the contrast for the red, green, * @param {Object} contrast: Object containing the contrast for the
* and blue channels. Values of 0.0 represent "standard" * red, green, and blue channels. Values of 0.0 represent "standard"
* contrast (no change), whereas values less or greater than * contrast (no change), whereas values less or greater than
* 0.0 indicate decreased or incresaed contrast, respectively. * 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) { setContrast(contrast) {
this._contrast.r = contrast.r; this._contrast.r = contrast.r;
@ -1262,8 +1271,8 @@ var ZoomRegion = class ZoomRegion {
/** /**
* getContrast: * getContrast:
* Retrieve the contrast of the magnified view. * Retrieve the contrast of the magnified view.
* @return Object containing the contrast for the red, green, * @returns {{r: number, g: number, b: number}}: Object containing
* and blue channels. * the contrast for the red, green, and blue channels.
*/ */
getContrast() { getContrast() {
let contrast = {}; let contrast = {};
@ -1627,11 +1636,12 @@ class Crosshairs extends Clutter.Actor {
* already part of some other ZoomRegion, create a clone of the crosshairs * already part of some other ZoomRegion, create a clone of the crosshairs
* actor, and add the clone instead. Returns either the original or the * actor, and add the clone instead. Returns either the original or the
* clone. * clone.
* @zoomRegion: The container to add the crosshairs group to. * @param {ZoomRegion} zoomRegion: The container to add the crosshairs
* @magnifiedMouse: The mouse actor for the zoom region -- used to * group to.
* position the crosshairs and properly layer them below * @param {Clutter.Actor} magnifiedMouse: The mouse actor for the
* the mouse. * zoom region -- used to position the crosshairs and properly
* @return The crosshairs actor, or its clone. * layer them below the mouse.
* @returns {Clutter.Actor} The crosshairs actor, or its clone.
*/ */
addToZoomRegion(zoomRegion, magnifiedMouse) { addToZoomRegion(zoomRegion, magnifiedMouse) {
let crosshairsActor = null; let crosshairsActor = null;
@ -1660,7 +1670,8 @@ class Crosshairs extends Clutter.Actor {
/** /**
* removeFromParent: * 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 * Remove the crosshairs actor from its parent container, or destroy the
* child actor if it was just a clone of the crosshairs actor. * child actor if it was just a clone of the crosshairs actor.
*/ */
@ -1674,7 +1685,7 @@ class Crosshairs extends Clutter.Actor {
/** /**
* setColor: * setColor:
* Set the color of the crosshairs. * Set the color of the crosshairs.
* @clutterColor: The color as a Clutter.Color. * @param {Clutter.Color} clutterColor: The color
*/ */
setColor(clutterColor) { setColor(clutterColor) {
this._horizLeftHair.background_color = clutterColor; this._horizLeftHair.background_color = clutterColor;
@ -1686,7 +1697,7 @@ class Crosshairs extends Clutter.Actor {
/** /**
* getColor: * getColor:
* Get the color of the crosshairs. * Get the color of the crosshairs.
* @color: The color as a Clutter.Color. * @returns {ClutterColor} the crosshairs color
*/ */
getColor() { getColor() {
return this._horizLeftHair.get_color(); return this._horizLeftHair.get_color();
@ -1695,7 +1706,7 @@ class Crosshairs extends Clutter.Actor {
/** /**
* setThickness: * setThickness:
* Set the width of the vertical and horizontal lines of the crosshairs. * Set the width of the vertical and horizontal lines of the crosshairs.
* @thickness * @param {number} thickness: the new thickness value
*/ */
setThickness(thickness) { setThickness(thickness) {
this._horizLeftHair.set_height(thickness); this._horizLeftHair.set_height(thickness);
@ -1708,7 +1719,7 @@ class Crosshairs extends Clutter.Actor {
/** /**
* getThickness: * getThickness:
* Get the width of the vertical and horizontal lines of the crosshairs. * 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() { getThickness() {
return this._horizLeftHair.get_height(); return this._horizLeftHair.get_height();
@ -1717,7 +1728,8 @@ class Crosshairs extends Clutter.Actor {
/** /**
* setOpacity: * setOpacity:
* Set how opaque the crosshairs are. * 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) { setOpacity(opacity) {
// set_opacity() throws an exception for values outside the range // set_opacity() throws an exception for values outside the range
@ -1736,7 +1748,7 @@ class Crosshairs extends Clutter.Actor {
/** /**
* setLength: * setLength:
* Set the length of the vertical and horizontal lines in the crosshairs. * 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) { setLength(length) {
this._horizLeftHair.set_width(length); this._horizLeftHair.set_width(length);
@ -1749,7 +1761,7 @@ class Crosshairs extends Clutter.Actor {
/** /**
* getLength: * getLength:
* Get the length of the vertical and horizontal lines in the crosshairs. * 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() { getLength() {
return this._horizLeftHair.get_width(); return this._horizLeftHair.get_width();
@ -1759,8 +1771,8 @@ class Crosshairs extends Clutter.Actor {
* setClip: * setClip:
* Set the width and height of the rectangle that clips the crosshairs at * Set the width and height of the rectangle that clips the crosshairs at
* their intersection * their intersection
* @size: Array of [width, height] defining the size of the clip * @param {number[]} size: Array of [width, height] defining the size
* rectangle. * of the clip rectangle.
*/ */
setClip(size) { setClip(size) {
if (size) { if (size) {
@ -1780,7 +1792,7 @@ class Crosshairs extends Clutter.Actor {
* Reposition the horizontal and vertical hairs such that they cross at * Reposition the horizontal and vertical hairs such that they cross at
* the center of crosshairs group. If called with the dimensions of * the center of crosshairs group. If called with the dimensions of
* the clip rectangle, these are used to update the size of the clip. * 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) { reCenter(clipSize) {
let [groupWidth, groupHeight] = this.get_size(); let [groupWidth, groupHeight] = this.get_size();
@ -1838,7 +1850,7 @@ var MagShaderEffects = class MagShaderEffects {
/** /**
* setInvertLightness: * setInvertLightness:
* Enable/disable invert lightness effect. * Enable/disable invert lightness effect.
* @invertFlag: Enabled flag. * @param {bool} invertFlag: Enabled flag.
*/ */
setInvertLightness(invertFlag) { setInvertLightness(invertFlag) {
this._inverse.set_enabled(invertFlag); this._inverse.set_enabled(invertFlag);
@ -1851,11 +1863,14 @@ var MagShaderEffects = class MagShaderEffects {
/** /**
* setBrightness: * setBrightness:
* Set the brightness of the magnified view. * Set the brightness of the magnified view.
* @brightness: Object containing the brightness for the red, green, * @param {Object} brightness: Object containing the contrast for the
* and blue channels. Values of 0.0 represent "standard" * red, green, and blue channels. Values of 0.0 represent "standard"
* brightness (no change), whereas values less or greater than * brightness (no change), whereas values less or greater than
* 0.0 indicate decreased or incresaed brightness, * 0.0 indicate decreased or incresaed brightness, respectively.
* respectively. *
* {number} brightness.r - the red component
* {number} brightness.g - the green component
* {number} brightness.b - the blue component
*/ */
setBrightness(brightness) { setBrightness(brightness) {
let bRed = brightness.r; let bRed = brightness.r;
@ -1874,10 +1889,14 @@ var MagShaderEffects = class MagShaderEffects {
/** /**
* Set the contrast of the magnified view. * Set the contrast of the magnified view.
* @contrast: Object containing the contrast for the red, green, * @param {Object} contrast: Object containing the contrast for the
* and blue channels. Values of 0.0 represent "standard" * red, green, and blue channels. Values of 0.0 represent "standard"
* contrast (no change), whereas values less or greater than * contrast (no change), whereas values less or greater than
* 0.0 indicate decreased or incresaed contrast, respectively. * 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) { setContrast(contrast) {
let cRed = contrast.r; let cRed = contrast.r;

89
js/ui/magnifierDBus.js
View File

@ -32,7 +32,7 @@ var ShellMagnifier = class ShellMagnifier {
/** /**
* setActive: * setActive:
* @activate: Boolean to activate or de-activate the magnifier. * @param {bool} activate: activate or de-activate the magnifier.
*/ */
setActive(activate) { setActive(activate) {
Main.magnifier.setActive(activate); Main.magnifier.setActive(activate);
@ -40,7 +40,7 @@ var ShellMagnifier = class ShellMagnifier {
/** /**
* isActive: * isActive:
* @return Whether the magnifier is active (boolean). * @returns {bool} Whether the magnifier is active.
*/ */
isActive() { isActive() {
return Main.magnifier.isActive(); return Main.magnifier.isActive();
@ -65,22 +65,25 @@ var ShellMagnifier = class ShellMagnifier {
/** /**
* createZoomRegion: * createZoomRegion:
* Create a new ZoomRegion and return its object path. * Create a new ZoomRegion and return its object path.
* @xMagFactor: The power to set horizontal magnification of the * @param {number} xMagFactor:
* ZoomRegion. A value of 1.0 means no magnification. A * The power to set horizontal magnification of the ZoomRegion.
* value of 2.0 doubles the size. * A value of 1.0 means no magnification. A value of 2.0 doubles
* @yMagFactor: The power to set the vertical magnification of the * the size.
* @param {number} yMagFactor:
* The power to set the vertical magnification of the
* ZoomRegion. * ZoomRegion.
* @roi Array of integers defining the region of the * @param {number[]} roi
* screen/desktop to magnify. The array has the form * Array of integers defining the region of the screen/desktop
* [left, top, right, bottom]. * to magnify. The array has the form [left, top, right, bottom].
* @viewPort Array of integers, [left, top, right, bottom] that defines * @param {number[]} viewPort
* Array of integers, [left, top, right, bottom] that defines
* the position of the ZoomRegion on screen. * the position of the ZoomRegion on screen.
* *
* FIXME: The arguments here are redundant, since the width and height of * FIXME: The arguments here are redundant, since the width and height of
* the ROI are determined by the viewport and magnification factors. * the ROI are determined by the viewport and magnification factors.
* We ignore the passed in width and height. * We ignore the passed in width and height.
* *
* @return The newly created ZoomRegion. * @returns {ZoomRegion} The newly created ZoomRegion.
*/ */
createZoomRegion(xMagFactor, yMagFactor, roi, viewPort) { createZoomRegion(xMagFactor, yMagFactor, roi, viewPort) {
let ROI = { x: roi[0], y: roi[1], width: roi[2] - roi[0], height: roi[3] - roi[1] }; 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: * addZoomRegion:
* Append the given ZoomRegion to the magnifier's list of ZoomRegions. * 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) { addZoomRegion(zoomerObjectPath) {
let proxyAndZoomRegion = this._zoomers[zoomerObjectPath]; let proxyAndZoomRegion = this._zoomers[zoomerObjectPath];
@ -115,8 +120,8 @@ var ShellMagnifier = class ShellMagnifier {
/** /**
* getZoomRegions: * getZoomRegions:
* Return a list of ZoomRegion object paths for this Magnifier. * Return a list of ZoomRegion object paths for this Magnifier.
* @return: The Magnifier's zoom region list as an array of DBus object * @returns {string[]}: The Magnifier's zoom region list as an array
* paths. * of DBus object paths.
*/ */
getZoomRegions() { getZoomRegions() {
// There may be more ZoomRegions in the magnifier itself than have // There may be more ZoomRegions in the magnifier itself than have
@ -169,7 +174,7 @@ var ShellMagnifier = class ShellMagnifier {
/** /**
* fullScreenCapable: * fullScreenCapable:
* Consult if the Magnifier can magnify in full-screen mode. * Consult if the Magnifier can magnify in full-screen mode.
* @return Always return true. * @returns {bool} Always return true.
*/ */
fullScreenCapable() { fullScreenCapable() {
return true; return true;
@ -178,7 +183,7 @@ var ShellMagnifier = class ShellMagnifier {
/** /**
* setCrosswireSize: * setCrosswireSize:
* Set the crosswire size of all ZoomRegions. * 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) { setCrosswireSize(size) {
Main.magnifier.setCrosshairsThickness(size); Main.magnifier.setCrosshairsThickness(size);
@ -187,7 +192,7 @@ var ShellMagnifier = class ShellMagnifier {
/** /**
* getCrosswireSize: * getCrosswireSize:
* Get the crosswire size of all ZoomRegions. * 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() { getCrosswireSize() {
return Main.magnifier.getCrosshairsThickness(); return Main.magnifier.getCrosshairsThickness();
@ -196,16 +201,16 @@ var ShellMagnifier = class ShellMagnifier {
/** /**
* setCrosswireLength: * setCrosswireLength:
* Set the crosswire length of all zoom-regions.. * 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) { setCrosswireLength(length) {
Main.magnifier.setCrosshairsLength(length); Main.magnifier.setCrosshairsLength(length);
} }
/** /**
* setCrosswireSize: * getCrosswireSize:
* Set the crosswire size of all zoom-regions. * Get the crosswire length of all zoom-regions.
* @size: The thickness of each line in the cross wire. * @returns {number} size: The length of each line in the cross wire.
*/ */
getCrosswireLength() { getCrosswireLength() {
return Main.magnifier.getCrosshairsLength(); return Main.magnifier.getCrosshairsLength();
@ -214,7 +219,7 @@ var ShellMagnifier = class ShellMagnifier {
/** /**
* setCrosswireClip: * setCrosswireClip:
* Set if the crosswire will be clipped by the cursor image.. * 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) { setCrosswireClip(clip) {
Main.magnifier.setCrosshairsClip(clip); Main.magnifier.setCrosshairsClip(clip);
@ -223,7 +228,7 @@ var ShellMagnifier = class ShellMagnifier {
/** /**
* getCrosswireClip: * getCrosswireClip:
* Get the crosswire clip value. * 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() { getCrosswireClip() {
return Main.magnifier.getCrosshairsClip(); return Main.magnifier.getCrosshairsClip();
@ -232,7 +237,7 @@ var ShellMagnifier = class ShellMagnifier {
/** /**
* setCrosswireColor: * setCrosswireColor:
* Set the crosswire color of all ZoomRegions. * 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) { setCrosswireColor(color) {
Main.magnifier.setCrosshairsColor('#%08x'.format(color)); Main.magnifier.setCrosshairsColor('#%08x'.format(color));
@ -241,7 +246,8 @@ var ShellMagnifier = class ShellMagnifier {
/** /**
* getCrosswireClip: * getCrosswireClip:
* Get the crosswire color of all ZoomRegions. * 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() { getCrosswireColor() {
let colorString = Main.magnifier.getCrosshairsColor(); let colorString = Main.magnifier.getCrosshairsColor();
@ -266,11 +272,11 @@ var ShellMagnifierZoomRegion = class ShellMagnifierZoomRegion {
/** /**
* setMagFactor: * setMagFactor:
* @xMagFactor: The power to set the horizontal magnification factor to * @param {number} xMagFactor: The power to set the horizontal
* of the magnified view. A value of 1.0 means no * magnification factor to of the magnified view. A value of
* magnification. A value of 2.0 doubles the size. * 1.0 means no magnification. A value of 2.0 doubles the size.
* @yMagFactor: The power to set the vertical magnification factor to * @param {number} yMagFactor: The power to set the vertical
* of the magnified view. * magnification factor to of the magnified view.
*/ */
setMagFactor(xMagFactor, yMagFactor) { setMagFactor(xMagFactor, yMagFactor) {
this._zoomRegion.setMagFactor(xMagFactor, yMagFactor); this._zoomRegion.setMagFactor(xMagFactor, yMagFactor);
@ -278,7 +284,7 @@ var ShellMagnifierZoomRegion = class ShellMagnifierZoomRegion {
/** /**
* getMagFactor: * 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 * and vertical magnification powers. A value of 1.0 means no
* magnification. A value of 2.0 means the contents are doubled * magnification. A value of 2.0 means the contents are doubled
* in size, and so on. * in size, and so on.
@ -290,9 +296,9 @@ var ShellMagnifierZoomRegion = class ShellMagnifierZoomRegion {
/** /**
* setRoi: * setRoi:
* Sets the "region of interest" that the ZoomRegion is magnifying. * Sets the "region of interest" that the ZoomRegion is magnifying.
* @roi Array, [left, top, right, bottom], defining the region of the * @param {number[]} roi: [left, top, right, bottom], defining the
* screen to magnify. The values are in screen (unmagnified) * region of the screen to magnify.
* coordinate space. * The values are in screen (unmagnified) coordinate space.
*/ */
setRoi(roi) { setRoi(roi) {
let roiObject = { x: roi[0], y: roi[1], width: roi[2] - roi[0], height: roi[3] - roi[1] }; 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 * Retrieves the "region of interest" -- the rectangular bounds of that part
* of the desktop that the magnified view is showing (x, y, width, height). * of the desktop that the magnified view is showing (x, y, width, height).
* The bounds are given in non-magnified coordinates. * 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. * rectangle of what is shown in the magnified view.
*/ */
getRoi() { getRoi() {
@ -317,10 +323,11 @@ var ShellMagnifierZoomRegion = class ShellMagnifierZoomRegion {
/** /**
* Set the "region of interest" by centering the given screen coordinate * Set the "region of interest" by centering the given screen coordinate
* within the zoom region. * within the zoom region.
* @x The x-coord of the point to place at the center of the zoom region. * @param {number} x: The x-coord of the point to place at the
* @y The y-coord. * center of the zoom region.
* @return Whether the shift was successful (for GS-mag, this is always * @param {number} y: The y-coord.
* true). * @returns {bool} Whether the shift was successful (for GS-mag, this
* is always true).
*/ */
shiftContentsTo(x, y) { shiftContentsTo(x, y) {
this._zoomRegion.scrollContentsTo(x, y); this._zoomRegion.scrollContentsTo(x, y);
@ -330,8 +337,8 @@ var ShellMagnifierZoomRegion = class ShellMagnifierZoomRegion {
/** /**
* moveResize * moveResize
* Sets the position and size of the ZoomRegion on screen. * Sets the position and size of the ZoomRegion on screen.
* @viewPort Array, [left, top, right, bottom], defining the position and * @param {number[]} viewPort: [left, top, right, bottom], defining
* size on screen to place the zoom region. * the position and size on screen to place the zoom region.
*/ */
moveResize(viewPort) { moveResize(viewPort) {
let viewRect = { x: viewPort[0], y: viewPort[1], width: viewPort[2] - viewPort[0], height: viewPort[3] - viewPort[1] }; let viewRect = { x: viewPort[0], y: viewPort[1], width: viewPort[2] - viewPort[0], height: viewPort[3] - viewPort[1] };

37
js/ui/main.js
View File

@ -337,7 +337,7 @@ function _loadDefaultStylesheet() {
* *
* Get the theme CSS file that the shell will load * 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 * null if using the default
*/ */
function getThemeStylesheet() { function getThemeStylesheet() {
@ -346,7 +346,7 @@ function getThemeStylesheet() {
/** /**
* setThemeStylesheet: * setThemeStylesheet:
* @cssStylesheet: A file path that contains the theme CSS, * @param {string=} cssStylesheet: A file path that contains the theme CSS,
* set it to null to use the default * set it to null to use the default
* *
* Set the theme CSS file that the shell will load * Set the theme CSS file that the shell will load
@ -397,8 +397,8 @@ function loadTheme() {
/** /**
* notify: * notify:
* @msg: A message * @param {string} msg: A message
* @details: Additional information * @param {string} details: Additional information
*/ */
function notify(msg, details) { function notify(msg, details) {
let source = new MessageTray.SystemNotificationSource(); let source = new MessageTray.SystemNotificationSource();
@ -410,8 +410,8 @@ function notify(msg, details) {
/** /**
* notifyError: * notifyError:
* @msg: An error message * @param {string} msg: An error message
* @details: Additional information * @param {string} details: Additional information
* *
* See shell_global_notify_problem(). * See shell_global_notify_problem().
*/ */
@ -435,8 +435,8 @@ function _findModal(actor) {
/** /**
* pushModal: * pushModal:
* @actor: #ClutterActor which will be given keyboard focus * @param {Clutter.Actor} actor: actor which will be given keyboard focus
* @params: optional parameters * @param {Object=} params: optional parameters
* *
* Ensure we are in a mode where all keyboard and mouse input goes to * 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 * 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 * global keybindings; the default of NONE will filter
* out all keybindings * 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) { function pushModal(actor, params) {
params = Params.parse(params, { timestamp: global.get_current_time(), params = Params.parse(params, { timestamp: global.get_current_time(),
@ -503,8 +503,9 @@ function pushModal(actor, params) {
/** /**
* popModal: * popModal:
* @actor: #ClutterActor passed to original invocation of pushModal() * @param {Clutter.Actor} actor: the actor passed to original invocation
* @timestamp: optional timestamp * of pushModal()
* @param {number=} timestamp: optional timestamp
* *
* Reverse the effect of pushModal(). If this invocation is undoing * Reverse the effect of pushModal(). If this invocation is undoing
* the topmost invocation, then the focus will be restored to the * the topmost invocation, then the focus will be restored to the
@ -590,9 +591,9 @@ function openRunDialog() {
/** /**
* activateWindow: * activateWindow:
* @window: the Meta.Window to activate * @param {Meta.Window} window: the window to activate
* @time: (optional) current event time * @param {number=} time: current event time
* @workspaceNum: (optional) window's workspace number * @param {number=} workspaceNum: window's workspace number
* *
* Activates @window, switching to its workspace first if necessary, * Activates @window, switching to its workspace first if necessary,
* and switching out of the overview if it's currently active * and switching out of the overview if it's currently active
@ -668,8 +669,8 @@ function _queueBeforeRedraw(workId) {
/** /**
* initializeDeferredWork: * initializeDeferredWork:
* @actor: A #ClutterActor * @param {Clutter.Actor} actor: an actor
* @callback: Function to invoke to perform work * @param {callback} callback: Function to invoke to perform work
* *
* This function sets up a callback to be invoked when either the * 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 * 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 * initialization as well, under the assumption that new actors
* will need it. * will need it.
* *
* Returns: A string work identifier * @returns {string}: A string work identifier
*/ */
function initializeDeferredWork(actor, callback) { function initializeDeferredWork(actor, callback) {
// Turn into a string so we can use as an object property // Turn into a string so we can use as an object property
@ -706,7 +707,7 @@ function initializeDeferredWork(actor, callback) {
/** /**
* queueDeferredWork: * queueDeferredWork:
* @workId: work identifier * @param {string} workId: work identifier
* *
* Ensure that the work identified by @workId will be * Ensure that the work identified by @workId will be
* run on map or timeout. You should call this function * run on map or timeout. You should call this function

4
js/ui/popupMenu.js
View File

@ -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) { function arrowIcon(side) {
let iconName; let iconName;

31
js/ui/scripting.js
View File

@ -32,7 +32,8 @@ const { loadInterfaceXML } = imports.misc.fileUtils;
/** /**
* sleep: * 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 * Used within an automation script to pause the the execution of the
* current script for the specified amount of time. Use as * current script for the specified amount of time. Use as
@ -50,6 +51,7 @@ function sleep(milliseconds) {
/** /**
* waitLeisure: * waitLeisure:
* @returns {Promise} that resolves when the shell is idle
* *
* Used within an automation script to pause the the execution of the * Used within an automation script to pause the the execution of the
* current script until the shell is completely idle. Use as * current script until the shell is completely idle. Use as
@ -90,13 +92,13 @@ function _callRemote(obj, method, ...args) {
/** /**
* createTestWindow: * createTestWindow:
* @params: options for window creation. * @param {Object} params: options for window creation.
* width - width of window, in pixels (default 640) * {number} [params.width=640] - width of window, in pixels
* height - height of window, in pixels (default 480) * {number} [params.height=480] - height of window, in pixels
* alpha - whether the window should have an alpha channel (default false) * {bool} [params.alpha=false] - whether the window should have an alpha channel
* maximized - whether the window should be created maximized (default false) * {bool} [params.maximized=false] - whether the window should be created maximized
* redraws - whether the window should continually redraw itself (default false) * {bool} [params.redraws=false] - whether the window should continually redraw itself
* @maximized: whethe the window should be created maximized * @returns {Promise}
* *
* Creates a window using gnome-shell-perf-helper for testing purposes. * Creates a window using gnome-shell-perf-helper for testing purposes.
* While this function can be used with yield in an automation * While this function can be used with yield in an automation
@ -119,6 +121,7 @@ function createTestWindow(params) {
/** /**
* waitTestWindows: * waitTestWindows:
* @returns {Promise}
* *
* Used within an automation script to pause until all windows previously * Used within an automation script to pause until all windows previously
* created with createTestWindow have been mapped and exposed. * created with createTestWindow have been mapped and exposed.
@ -130,6 +133,7 @@ function waitTestWindows() {
/** /**
* destroyTestWindows: * destroyTestWindows:
* @returns {Promise}
* *
* Destroys all windows previously created with createTestWindow(). * Destroys all windows previously created with createTestWindow().
* While this function can be used with yield in an automation * While this function can be used with yield in an automation
@ -144,8 +148,8 @@ function destroyTestWindows() {
/** /**
* defineScriptEvent * defineScriptEvent
* @name: The event will be called script.<name> * @param {string} name: The event will be called script.<name>
* @description: Short human-readable description of the event * @param {string} description: Short human-readable description of the event
* *
* Convenience function to define a zero-argument performance event * Convenience function to define a zero-argument performance event
* within the 'script' namespace that is reserved for events defined locally * within the 'script' namespace that is reserved for events defined locally
@ -159,7 +163,7 @@ function defineScriptEvent(name, description) {
/** /**
* scriptEvent * scriptEvent
* @name: Name registered with defineScriptEvent() * @param {string} name: Name registered with defineScriptEvent()
* *
* Convenience function to record a script-local performance event * Convenience function to record a script-local performance event
* previously defined with defineScriptEvent * previously defined with defineScriptEvent
@ -274,8 +278,9 @@ function _collect(scriptModule, outputFile) {
/** /**
* runPerfScript * runPerfScript
* @scriptModule: module object with run and finish functions * @param {Object} scriptModule: module object with run and finish
* and event handlers * functions and event handlers
* @param {string} outputFile: path to write output to
* *
* Runs a script for automated collection of performance data. The * Runs a script for automated collection of performance data. The
* script is defined as a Javascript module with specified contents. * script is defined as a Javascript module with specified contents.

3
js/ui/shellDBus.js
View File

@ -39,7 +39,8 @@ var GnomeShell = class {
/** /**
* Eval: * 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 * This function executes arbitrary code in the main
* loop, and returns a boolean success and * loop, and returns a boolean success and

59
js/ui/shellMountOperation.js
View File

@ -618,18 +618,22 @@ var GnomeShellMountOpHandler = class {
/** /**
* AskPassword: * AskPassword:
* @id: an opaque ID identifying the object for which the operation is requested * @param {Array} params
* The ID must be unique in the context of the calling process. * {string} id: an opaque ID identifying the object for which
* @message: the message to display * the operation is requested
* @icon_name: the name of an icon to display * {string} message: the message to display
* @default_user: the default username for display * {string} icon_name: the name of an icon to display
* @default_domain: the default domain for display * {string} default_user: the default username for display
* @flags: a set of GAskPasswordFlags * {string} default_domain: the default domain for display
* @response: a GMountOperationResult * {Gio.AskPasswordFlags} flags: a set of GAskPasswordFlags
* @response_details: a dictionary containing the response details as * {Gio.MountOperationResults} response: a GMountOperationResult
* entered by the user. The dictionary MAY contain the following properties: * {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" -> (s): a password to be used to complete the mount operation
* - "password_save" -> (u): a GPasswordSave * - "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 * The dialog will stay visible until clients call the Close() method, or
* another dialog becomes visible. * another dialog becomes visible.
@ -673,16 +677,14 @@ var GnomeShellMountOpHandler = class {
/** /**
* AskQuestion: * 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. * The ID must be unique in the context of the calling process.
* @message: the message to display * {string} message: the message to display
* @icon_name: the name of an icon to display * {string} icon_name: the name of an icon to display
* @choices: an array of choice strings * {string[]} choices: an array of choice strings
* GetResponse: * @param {Gio.DBusMethodInvocation} invocation - invocation
* @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
* *
* The dialog will stay visible until clients call the Close() method, or * The dialog will stay visible until clients call the Close() method, or
* another dialog becomes visible. * another dialog becomes visible.
@ -711,16 +713,15 @@ var GnomeShellMountOpHandler = class {
/** /**
* ShowProcesses: * 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. * The ID must be unique in the context of the calling process.
* @message: the message to display * {string} message: the message to display
* @icon_name: the name of an icon to display * {string} icon_name: the name of an icon to display
* @application_pids: the PIDs of the applications to display * {number[]} application_pids: the PIDs of the applications to display
* @choices: an array of choice strings * {string[]} choices: an array of choice strings
* @response: a GMountOperationResult * @param {Gio.DBusMethodInvocation} invocation - invocation
* @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
* *
* The dialog will stay visible until clients call the Close() method, or * The dialog will stay visible until clients call the Close() method, or
* another dialog becomes visible. * another dialog becomes visible.
@ -759,6 +760,8 @@ var GnomeShellMountOpHandler = class {
/** /**
* Close: * Close:
* @param {Array} _params - params
* @param {Gio.DBusMethodInvocation} _invocation - invocation
* *
* Closes a dialog previously opened by AskPassword, AskQuestion or ShowProcesses. * Closes a dialog previously opened by AskPassword, AskQuestion or ShowProcesses.
* If no dialog is open, does nothing. * If no dialog is open, does nothing.