From 61210fdae146670cd710011717b4a1a89d71f932 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Florian=20M=C3=BCllner?= <fmuellner@gnome.org>
Date: Thu, 17 Oct 2019 18:41:52 +0200
Subject: [PATCH] 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 37423d39a..020042c8a 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 9ddc42856..473ad0758 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 741df63c4..855cd0e98 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 953990034..e6ea64224 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 07de7ad4f..75edfe7c2 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 ff3d79c33..6d6ff5cbe 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 f48296425..5446696a8 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 4bdd546ba..9f8ee2825 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 b797d2bcc..6f962d13a 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 8419fd436..09b0249aa 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 acd89265e..53a1cd170 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 5b7137603..ee775e4f0 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 8b3db8fc0..22d9e65e9 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 61dc9171e..4934ee426 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.