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

cleanup: Fixup wrong JSDoc comments

Browse Source 
There are a handful of JSDoc comments that are invalid or don't
conform to the configured format. Fix them to remove the last
remaining bit of legacy configuration.

Part-of: <https://gitlab.gnome.org/GNOME/gnome-shell/-/merge_requests/2866>
This commit is contained in:
Florian Müllner 2023-08-07 03:15:51 +02:00 committed by Marge Bot
parent a42f7c2384
commit ff010a11ab
15 changed files with 119 additions and 170 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

7
js/dbusServices/dbusService.js
View File

@ -59,13 +59,12 @@ export class ServiceImplementation {
}
/**
* _handleError:
* @param {Gio.DBusMethodInvocation}
* @param {Error}
*
* Complete @invocation with an appropriate error if @error is set;
* useful for implementing early returns from method implementations.
*
* @param {Gio.DBusMethodInvocation}
* @param {Error}
*
* @returns {bool} - true if @invocation was completed
*/

2
js/misc/loginManager.js
View File

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

20
js/misc/signalTracker.js
View File

@ -4,7 +4,7 @@ const destroyableTypes = [];
/**
* @private
* @param {Object} obj - an object
* @param {object} obj - an object
* @returns {bool} - true if obj has a 'destroy' GObject signal
*/
function _hasDestroySignal(obj) {
@ -51,7 +51,7 @@ class SignalManager {
}
/**
* @param {Object} obj - object to get signal tracker for
* @param {object} obj - object to get signal tracker for
* @returns {SignalTracker} - the signal tracker for object
*/
getSignalTracker(obj) {
@ -64,7 +64,7 @@ class SignalManager {
}
/**
* @param {Object} obj - object to get signal tracker for
* @param {object} obj - object to get signal tracker for
* @returns {?SignalTracker} - the signal tracker for object if it exists
*/
maybeGetSignalTracker(obj) {
@ -72,7 +72,7 @@ class SignalManager {
}
/*
* @param {Object} obj - object to remove signal tracker for
* @param {object} obj - object to remove signal tracker for
* @returns {void}
*/
removeSignalTracker(obj) {
@ -82,7 +82,7 @@ class SignalManager {
class SignalTracker {
/**
* @param {Object=} owner - object that owns the tracker
* @param {object=} owner - object that owns the tracker
*/
constructor(owner) {
if (_hasDestroySignal(owner))
@ -100,7 +100,7 @@ class SignalTracker {
/**
* @private
* @param {Object} obj - a tracked object
* @param {object} obj - a tracked object
* @returns {SignalData} - signal data for object
*/
_getSignalData(obj) {
@ -148,7 +148,7 @@ class SignalTracker {
}
/**
* @param {Object} obj - tracked object
* @param {object} obj - tracked object
* @param {...number} handlerIds - tracked handler IDs
* @returns {void}
*/
@ -160,7 +160,7 @@ class SignalTracker {
}
/**
* @param {Object} obj - tracked object instance
* @param {object} obj - tracked object instance
* @returns {void}
*/
untrack(obj) {
@ -249,8 +249,8 @@ export function connectObject(thisObj, ...args) {
* Disconnect all signals that were connected for
* the specified tracked object
*
* @param {Object} thisObj - the emitter object
* @param {Object} obj - the tracked object
* @param {object} thisObj - the emitter object
* @param {object} obj - the tracked object
* @returns {void}
*/
export function disconnectObject(thisObj, obj) {

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

@ -692,15 +692,14 @@ const ChatNotification = HAVE_TP ? GObject.registerClass({
}
/**
* appendMessage:
* @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
* @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
*
* @param {bool} noTimestamp: Whether to add a timestamp. If %true,
* @param {bool} noTimestamp - Whether to add a timestamp. If %true,
* no timestamp will be added, regardless of the difference since
* the last timestamp
*/
@ -759,14 +758,13 @@ const ChatNotification = HAVE_TP ? GObject.registerClass({
}
/**
* _append:
* @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:
* @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'.
* {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?
* {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;

24
js/ui/dnd.js
View File

@ -336,8 +336,6 @@ class _Draggable extends Signals.EventEmitter {
}
/**
* fakeRelease:
*
* Fake a release event.
* Must be called if you want to intercept release events on draggable
* actors for other purposes (for example if you're using
@ -348,16 +346,15 @@ class _Draggable extends Signals.EventEmitter {
}
/**
* startDrag:
* @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
* for the draggable.
*
* @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
*/
startDrag(stageX, stageY, time, sequence, device) {
if (currentDraggable)
@ -870,11 +867,6 @@ class _Draggable extends Signals.EventEmitter {
}
/**
* makeDraggable:
* @param {Clutter.Actor} actor Source actor
* @param {object} [params] Additional parameters
* @returns {_Draggable} a new Draggable
*
* Create an object which controls drag and drop for the given actor.
*
* If %manualMode is %true in @params, do not automatically start
@ -890,6 +882,10 @@ class _Draggable extends Signals.EventEmitter {
* succeeds, the actor scale and opacity aren't reset; if the drop
* target wants to reuse the actor, it's up to the drop target to
* reset these values.
*
* @param {Clutter.Actor} actor Source actor
* @param {object} [params] Additional parameters
* @returns {_Draggable} a new Draggable
*/
export function makeDraggable(actor, params) {
return new _Draggable(actor, params);

31
js/ui/magnifier.js
View File

@ -436,7 +436,6 @@ export class Magnifier extends Signals.EventEmitter {
}
/**
* getCrosshairsThickness:
* Get the crosshairs thickness.
*
* @returns {number} The width of the vertical and horizontal
@ -450,8 +449,6 @@ export class Magnifier extends Signals.EventEmitter {
}
/**
* setCrosshairsOpacity:
*
* @param {number} opacity Value between 0.0 (transparent)
* and 1.0 (fully opaque).
*/
@ -461,7 +458,6 @@ export class Magnifier extends Signals.EventEmitter {
}
/**
* getCrosshairsOpacity:
* @returns {number} Value between 0.0 (transparent) and 1.0 (fully opaque).
*/
getCrosshairsOpacity() {
@ -472,8 +468,6 @@ export class Magnifier extends Signals.EventEmitter {
}
/**
* setCrosshairsLength:
*
* Set the crosshairs length for all ZoomRegions.
*
* @param {number} length The length of the vertical and horizontal
@ -1865,19 +1859,18 @@ class Crosshairs extends Clutter.Actor {
}
/**
* addToZoomRegion
* Either add the crosshairs actor to the given ZoomRegion, or, if it is
* already part of some other ZoomRegion, create a clone of the crosshairs
* actor, and add the clone instead. Returns either the original or the
* clone.
*
* @param {ZoomRegion} zoomRegion The container to add the crosshairs
* 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.
*/
* Either add the crosshairs actor to the given ZoomRegion, or, if it is
* already part of some other ZoomRegion, create a clone of the crosshairs
* actor, and add the clone instead. Returns either the original or the
* clone.
*
* @param {ZoomRegion} zoomRegion The container to add the crosshairs
* 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;
if (zoomRegion && magnifiedMouse) {

52
js/ui/main.js
View File

@ -444,8 +444,6 @@ function _loadDefaultStylesheet() {
}
/**
* getThemeStylesheet:
*
* Get the theme CSS file that the shell will load
*
* @returns {?Gio.File}: A #GFile that contains the theme CSS,
@ -456,11 +454,10 @@ export function getThemeStylesheet() {
}
/**
* setThemeStylesheet:
* @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
*
* @param {string=} cssStylesheet - A file path that contains the theme CSS,
* set it to null to use the default
*/
export function setThemeStylesheet(cssStylesheet) {
_cssStylesheet = cssStylesheet ? Gio.File.new_for_path(cssStylesheet) : null;
@ -514,8 +511,6 @@ export function loadTheme() {
}
/**
* notify:
*
* @param {string} msg A message
* @param {string} details Additional information
*/
@ -528,11 +523,10 @@ export function notify(msg, details) {
}
/**
* notifyError:
* @param {string} msg: An error message
* @param {string} details: Additional information
*
* See shell_global_notify_problem().
*
* @param {string} msg - An error message
* @param {string} details - Additional information
*/
export function notifyError(msg, details) {
// Also print to stderr so it's logged somewhere
@ -545,12 +539,8 @@ export function notifyError(msg, details) {
}
/**
* _findModal:
*
* @private
* @param {Clutter.Grab} grab - grab
*
* Private function.
*
*/
function _findModal(grab) {
for (let i = 0; i < modalActorFocusStack.length; i++) {
@ -561,10 +551,6 @@ function _findModal(grab) {
}
/**
* pushModal:
* @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
* a stacking fashion; the effect will be undone when an equal number
@ -574,7 +560,7 @@ function _findModal(grab) {
* modal stack returns to this actor, reset the focus to the actor
* which was focused at the time pushModal() was invoked.
*
* @params may be used to provide the following parameters:
* `params` may be used to provide the following parameters:
* - timestamp: used to associate the call with a specific user initiated
* event. If not provided then the value of
* global.get_current_time() is assumed.
@ -586,7 +572,9 @@ function _findModal(grab) {
* global keybindings; the default of NONE will filter
* out all keybindings
*
* @returns {Clutter.Grab}: the grab handle created
* @param {Clutter.Actor} actor - actor which will be given keyboard focus
* @param {object=} params - optional parameters
* @returns {Clutter.Grab} - the grab handle created
*/
export function pushModal(actor, params) {
params = Params.parse(params, {
@ -633,17 +621,16 @@ export function pushModal(actor, params) {
}
/**
* popModal:
* @param {Clutter.Grab} grab - the grab given by 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
* previous focus at the time when pushModal() was invoked.
*
* @timestamp is optionally used to associate the call with a specific user
* `timestamp` is optionally used to associate the call with a specific user
* initiated event. If not provided then the value of
* global.get_current_time() is assumed.
*
* @param {Clutter.Grab} grab - the grab given by pushModal()
* @param {number=} timestamp - optional timestamp
*/
export function popModal(grab, timestamp) {
if (timestamp === undefined)
@ -842,10 +829,6 @@ function _queueBeforeRedraw(workId) {
}
/**
* initializeDeferredWork:
* @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
* is idle. This is useful if your actor isn't always visible on the
@ -857,7 +840,10 @@ function _queueBeforeRedraw(workId) {
* initialization as well, under the assumption that new actors
* will need it.
*
* @returns {string}: A string work identifier
* @param {Clutter.Actor} actor - an actor
* @param {callback} callback - Function to invoke to perform work
*
* @returns {string} - A string work identifier
*/
export function initializeDeferredWork(actor, callback) {
// Turn into a string so we can use as an object property

2
js/ui/screenshot.js
View File

@ -2239,7 +2239,7 @@ function _storeScreenshot(bytes, pixbuf) {
* @param {Cogl.Texture} texture - The texture to take the screenshot from.
* @param {number[4]} [geometry] - The region to use: x, y, width and height.
* @param {number} scale - The texture scale.
* @param {Object} [cursor] - Cursor data to include in the screenshot.
* @param {object} [cursor] - Cursor data to include in the screenshot.
* @param {Cogl.Texture} cursor.texture - The cursor texture.
* @param {number} cursor.x - The cursor x coordinate.
* @param {number} cursor.y - The cursor y coordinate.

12
js/ui/scripting.js
View File

@ -30,13 +30,12 @@ import {loadInterfaceXML} from '../misc/fileUtils.js';
//
/**
* sleep:
* @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
* 'yield Scripting.sleep(500);'
*
* @param {number} milliseconds - number of milliseconds to wait
* @returns {Promise} that resolves after @milliseconds ms
*/
export function sleep(milliseconds) {
return new Promise(resolve => {
@ -49,12 +48,11 @@ export 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
* 'yield Scripting.waitLeisure();'
*
* @returns {Promise} that resolves when the shell is idle
*/
export function waitLeisure() {
return new Promise(resolve => {

6
js/ui/shellDBus.js
View File

@ -47,10 +47,6 @@ export class GnomeShell {
}
/**
* Eval:
* @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
* JSON representation of the object as a string.
@ -60,6 +56,8 @@ export class GnomeShell {
* If evaluation fails, then the return value will be
* [false, JSON.stringify(exception)];
*
* @param {string} code A string containing JavaScript code
* @returns {Array}
*/
Eval(code) {
if (!global.context.unsafe_mode)

44
js/ui/shellMountOperation.js
View File

@ -592,7 +592,12 @@ export class GnomeShellMountOpHandler {
}
/**
* AskPassword:
* The dialog will stay visible until clients call the Close() method, or
* another dialog becomes visible.
* Calling AskPassword again for the same id will have the effect to clear
* the existing dialog and update it with a message indicating the previous
* attempt went wrong.
*
* @param {Array} params
* {string} id: an opaque ID identifying the object for which
* the operation is requested
@ -609,12 +614,6 @@ export class GnomeShellMountOpHandler {
* - "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.
* Calling AskPassword again for the same id will have the effect to clear
* the existing dialog and update it with a message indicating the previous
* attempt went wrong.
*/
AskPasswordAsync(params, invocation) {
let [id, message, iconName_, defaultUser_, defaultDomain_, flags] = params;
@ -651,7 +650,11 @@ export class GnomeShellMountOpHandler {
}
/**
* AskQuestion:
* The dialog will stay visible until clients call the Close() method, or
* another dialog becomes visible.
* Calling AskQuestion again for the same id will have the effect to clear
* update the dialog with the new question.
*
* @param {Array} params - params
* {string} id: an opaque ID identifying the object for which
* the operation is requested
@ -660,11 +663,6 @@ export class GnomeShellMountOpHandler {
* {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.
* Calling AskQuestion again for the same id will have the effect to clear
* update the dialog with the new question.
*/
AskQuestionAsync(params, invocation) {
let [id, message, iconName_, choices] = params;
@ -696,7 +694,12 @@ export class GnomeShellMountOpHandler {
}
/**
* ShowProcesses:
* The dialog will stay visible until clients call the Close() method, or
* another dialog becomes visible.
* Calling ShowProcesses again for the same id will have the effect to clear
* the existing dialog and update it with the new message and the new list
* of processes.
*
* @param {Array} params - params
* {string} id: an opaque ID identifying the object for which
* the operation is requested
@ -706,12 +709,6 @@ export class GnomeShellMountOpHandler {
* {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.
* Calling ShowProcesses again for the same id will have the effect to clear
* the existing dialog and update it with the new message and the new list
* of processes.
*/
ShowProcessesAsync(params, invocation) {
let [id, message, iconName_, applicationPids, choices] = params;
@ -743,12 +740,11 @@ export class GnomeShellMountOpHandler {
}
/**
* 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.
*
* @param {Array} _params - params
* @param {Gio.DBusMethodInvocation} _invocation - invocation
*/
Close(_params, _invocation) {
this._clearCurrentRequest(Gio.MountOperationResult.UNHANDLED, {});

14
js/ui/swipeTracker.js
View File

@ -747,19 +747,17 @@ export const SwipeTracker = GObject.registerClass({
}
/**
* confirmSwipe:
* @param {number} distance: swipe distance in pixels
* @param {number[]} snapPoints:
* An array of snap points, sorted in ascending order
* @param {number} currentProgress: initial progress value
* @param {number} cancelProgress: the value to be used on cancelling
*
* Confirms a swipe. User has to call this in 'begin' signal handler,
* otherwise the swipe wouldn't start. If there's an animation running,
* it should be stopped first.
*
* @cancel_progress must always be a snap point, or a value matching
* `cancelProgress` must always be a snap point, or a value matching
* some other non-transient state.
*
* @param {number} distance - swipe distance in pixels
* @param {number[]} snapPoints - An array of snap points, sorted in ascending order
* @param {number} currentProgress - initial progress value
* @param {number} cancelProgress - the value to be used on cancelling
*/
confirmSwipe(distance, snapPoints, currentProgress, cancelProgress) {
this.distance = distance;

28
js/ui/workspace.js
View File

@ -779,8 +779,6 @@ export const WorkspaceLayout = GObject.registerClass({
}
/**
* syncOverlays:
*
* Synchronizes the overlay state of all window previews.
*/
syncOverlays() {
@ -788,14 +786,13 @@ export const WorkspaceLayout = GObject.registerClass({
}
/**
* addWindow:
* @param {WindowPreview} window: the window to add
* @param {Meta.Window} metaWindow: the MetaWindow of the window
*
* Adds @window to the workspace, it will be shown immediately if
* Adds `window` to the workspace, it will be shown immediately if
* the layout isn't frozen using the layout-frozen property.
*
* If @window is already part of the workspace, nothing will happen.
* If `window` is already part of the workspace, nothing will happen.
*
* @param {WindowPreview} window - the window to add
* @param {Meta.Window} metaWindow - the MetaWindow of the window
*/
addWindow(window, metaWindow) {
if (this._windows.has(window))
@ -829,12 +826,11 @@ export const WorkspaceLayout = GObject.registerClass({
}
/**
* removeWindow:
* @param {WindowPreview} window: the window to remove
*
* Removes @window from the workspace if @window is a part of the
* Removes `window` from the workspace if `window` is a part of the
* workspace. If the layout-frozen property is set to true, the
* window will still be visible until the property is set to false.
*
* @param {WindowPreview} window - the window to remove
*/
removeWindow(window) {
const windowInfo = this._windows.get(window);
@ -1033,11 +1029,13 @@ class WorkspaceBackground extends Shell.WorkspaceBackground {
}
});
/**
* @metaWorkspace: a #Meta.Workspace, or null
*/
export const Workspace = GObject.registerClass(
class Workspace extends St.Widget {
/**
* @param {Meta.Workspace} metaWorkspace
* @param {number} monitorIndex
* @param {OverviewAdjustment} overviewAdjustment
*/
_init(metaWorkspace, monitorIndex, overviewAdjustment) {
super._init({
style_class: 'window-picker',

7
js/ui/workspaceThumbnail.js
View File

@ -223,9 +223,6 @@ const ThumbnailState = {
DESTROYED: 9,
};
/**
* @metaWorkspace: a #Meta.Workspace
*/
export const WorkspaceThumbnail = GObject.registerClass({
Properties: {
'collapse-fraction': GObject.ParamSpec.double(
@ -238,6 +235,10 @@ export const WorkspaceThumbnail = GObject.registerClass({
0, 1, 0),
},
}, class WorkspaceThumbnail extends St.Widget {
/**
* @param {Meta.Workspace} metaWorkspace
* @param {number} monitorIndex
*/
_init(metaWorkspace, monitorIndex) {
super._init({
clip_to_allocation: true,

12
lint/eslintrc-legacy.yml
View File

@ -1,12 +0,0 @@
rules:
jsdoc/check-alignment: off
jsdoc/check-param-names: off
jsdoc/check-tag-names: off
jsdoc/check-types: off
jsdoc/implements-on-classes: off
jsdoc/tag-lines: off
jsdoc/require-jsdoc: off
jsdoc/require-param: off
jsdoc/require-param-description: off
jsdoc/require-param-name: off
jsdoc/require-param-type: off