GNOME.org
 

[gnome-shell-extensions] cleanup: Document functions

commit d0b9c9b54ad412f6e35e604fb9682ce961a17cce
Author: Florian Müllner <fmuellner gnome org>
Date:   Fri Aug 13 02:21:10 2021 +0200

    cleanup: Document functions
    
    gjs now enforces this in its eslint configuration. Adding type
    information generally is a good idea, so add appropriate comments
    to public functions before picking up that configuration change.
    
    Part-of: <https://gitlab.gnome.org/GNOME/gnome-shell-extensions/-/merge_requests/180>

 extensions/apps-menu/extension.js               |  3 +++
 extensions/auto-move-windows/extension.js       |  6 ++++++
 extensions/auto-move-windows/prefs.js           |  4 ++++
 extensions/drive-menu/extension.js              |  3 +++
 extensions/launch-new-instance/extension.js     |  2 ++
 extensions/native-window-placement/extension.js |  8 ++++++++
 extensions/places-menu/extension.js             |  3 +++
 extensions/screenshot-window-sizer/extension.js | 11 +++++++++++
 extensions/user-theme/extension.js              |  3 +++
 extensions/user-theme/prefs.js                  |  4 ++++
 extensions/user-theme/util.js                   |  6 ++++++
 extensions/window-list/extension.js             |  8 +++++++-
 extensions/window-list/prefs.js                 |  5 ++++-
 extensions/windowsNavigator/extension.js        |  3 +++
 extensions/workspace-indicator/extension.js     |  3 +++
 extensions/workspace-indicator/prefs.js         |  4 ++++
 16 files changed, 74 insertions(+), 2 deletions(-)
---
diff --git a/extensions/apps-menu/extension.js b/extensions/apps-menu/extension.js
index e36b0fe..431328d 100644
--- a/extensions/apps-menu/extension.js
+++ b/extensions/apps-menu/extension.js
@@ -674,17 +674,20 @@ class ApplicationsButton extends PanelMenu.Button {
 
 let appsMenuButton;
 
+/** */
 function enable() {
     appsMenuButton = new ApplicationsButton();
     let index = Main.sessionMode.panel.left.indexOf('activities') + 1;
     Main.panel.addToStatusArea('apps-menu', appsMenuButton, index, 'left');
 }
 
+/** */
 function disable() {
     Main.panel.menuManager.removeMenu(appsMenuButton.menu);
     appsMenuButton.destroy();
 }
 
+/** */
 function init() {
     ExtensionUtils.initTranslations();
 }
diff --git a/extensions/auto-move-windows/extension.js b/extensions/auto-move-windows/extension.js
index 3859809..72fed2e 100644
--- a/extensions/auto-move-windows/extension.js
+++ b/extensions/auto-move-windows/extension.js
@@ -108,10 +108,14 @@ class WindowMover {
 let prevCheckWorkspaces;
 let winMover;
 
+/** */
 function init() {
     ExtensionUtils.initTranslations();
 }
 
+/**
+ * @returns {bool} - false (used as MetaLater handler)
+ */
 function myCheckWorkspaces() {
     let keepAliveWorkspaces = [];
     let foundNonEmpty = false;
@@ -132,6 +136,7 @@ function myCheckWorkspaces() {
     return false;
 }
 
+/** */
 function enable() {
     prevCheckWorkspaces = Main.wm._workspaceTracker._checkWorkspaces;
     Main.wm._workspaceTracker._checkWorkspaces = myCheckWorkspaces;
@@ -139,6 +144,7 @@ function enable() {
     winMover = new WindowMover();
 }
 
+/** */
 function disable() {
     Main.wm._workspaceTracker._checkWorkspaces = prevCheckWorkspaces;
     winMover.destroy();
diff --git a/extensions/auto-move-windows/prefs.js b/extensions/auto-move-windows/prefs.js
index 2c52906..869cdb1 100644
--- a/extensions/auto-move-windows/prefs.js
+++ b/extensions/auto-move-windows/prefs.js
@@ -267,10 +267,14 @@ class NewRuleDialog extends Gtk.AppChooserDialog {
     }
 });
 
+/** */
 function init() {
     ExtensionUtils.initTranslations();
 }
 
+/**
+ * @returns {Gtk.Widget} - the prefs widget
+ */
 function buildPrefsWidget() {
     return new AutoMoveSettingsWidget();
 }
diff --git a/extensions/drive-menu/extension.js b/extensions/drive-menu/extension.js
index fd3a921..6cc91b2 100644
--- a/extensions/drive-menu/extension.js
+++ b/extensions/drive-menu/extension.js
@@ -218,17 +218,20 @@ class DriveMenu extends PanelMenu.Button {
     }
 });
 
+/** */
 function init() {
     ExtensionUtils.initTranslations();
 }
 
 let _indicator;
 
+/** */
 function enable() {
     _indicator = new DriveMenu();
     Main.panel.addToStatusArea('drive-menu', _indicator);
 }
 
+/** */
 function disable() {
     _indicator.destroy();
 }
diff --git a/extensions/launch-new-instance/extension.js b/extensions/launch-new-instance/extension.js
index 12a8df2..a249cd4 100644
--- a/extensions/launch-new-instance/extension.js
+++ b/extensions/launch-new-instance/extension.js
@@ -3,6 +3,7 @@ const AppDisplay = imports.ui.appDisplay;
 
 let _activateOriginal = null;
 
+/** */
 function enable() {
     _activateOriginal = AppDisplay.AppIcon.prototype.activate;
     AppDisplay.AppIcon.prototype.activate = function () {
@@ -10,6 +11,7 @@ function enable() {
     };
 }
 
+/** */
 function disable() {
     AppDisplay.AppIcon.prototype.activate = _activateOriginal;
 }
diff --git a/extensions/native-window-placement/extension.js b/extensions/native-window-placement/extension.js
index 018a742..35c31a4 100644
--- a/extensions/native-window-placement/extension.js
+++ b/extensions/native-window-placement/extension.js
@@ -238,11 +238,13 @@ class NaturalLayoutStrategy extends Workspace.LayoutStrategy {
 
 let winInjections, workspaceInjections;
 
+/** */
 function resetState() {
     winInjections = { };
     workspaceInjections = { };
 }
 
+/** */
 function enable() {
     resetState();
 
@@ -282,6 +284,11 @@ function enable() {
     };
 }
 
+/**
+ * @param {Object} object - object that was modified
+ * @param {Object} injection - the map of previous injections
+ * @param {string} name - the @injection key that should be removed
+ */
 function removeInjection(object, injection, name) {
     if (injection[name] === undefined)
         delete object[name];
@@ -289,6 +296,7 @@ function removeInjection(object, injection, name) {
         object[name] = injection[name];
 }
 
+/** */
 function disable() {
     var i;
 
diff --git a/extensions/places-menu/extension.js b/extensions/places-menu/extension.js
index e3b04d6..07a83f4 100644
--- a/extensions/places-menu/extension.js
+++ b/extensions/places-menu/extension.js
@@ -134,12 +134,14 @@ class PlacesMenu extends PanelMenu.Button {
     }
 });
 
+/** */
 function init() {
     ExtensionUtils.initTranslations();
 }
 
 let _indicator;
 
+/** */
 function enable() {
     _indicator = new PlacesMenu();
 
@@ -149,6 +151,7 @@ function enable() {
     Main.panel.addToStatusArea('places-menu', _indicator, pos, 'left');
 }
 
+/** */
 function disable() {
     _indicator.destroy();
 }
diff --git a/extensions/screenshot-window-sizer/extension.js b/extensions/screenshot-window-sizer/extension.js
index 1a7634c..997bb70 100644
--- a/extensions/screenshot-window-sizer/extension.js
+++ b/extensions/screenshot-window-sizer/extension.js
@@ -28,11 +28,15 @@ const MESSAGE_FADE_TIME = 2000;
 
 let text;
 
+/** */
 function hideMessage() {
     text.destroy();
     text = null;
 }
 
+/**
+ * @param {string} message - the message to flash
+ */
 function flashMessage(message) {
     if (!text) {
         text = new St.Label({ style_class: 'screenshot-sizer-message' });
@@ -67,6 +71,11 @@ let SIZES = [
     [720, 360], // Phone landscape fullscreen
 ];
 
+/**
+ * @param {Meta.Display} display - the display
+ * @param {Meta.Window=} window - for per-window bindings, the window
+ * @param {Meta.KeyBinding} binding - the key binding
+ */
 function cycleScreenshotSizes(display, window, binding) {
     // Probably this isn't useful with 5 sizes, but you can decrease instead
     // of increase by holding down shift.
@@ -133,6 +142,7 @@ function cycleScreenshotSizes(display, window, binding) {
     flashMessage(message);
 }
 
+/** */
 function enable() {
     Main.wm.addKeybinding(
         'cycle-screenshot-sizes',
@@ -148,6 +158,7 @@ function enable() {
         cycleScreenshotSizes);
 }
 
+/** */
 function disable() {
     Main.wm.removeKeybinding('cycle-screenshot-sizes');
     Main.wm.removeKeybinding('cycle-screenshot-sizes-backward');
diff --git a/extensions/user-theme/extension.js b/extensions/user-theme/extension.js
index 9986626..f54f757 100644
--- a/extensions/user-theme/extension.js
+++ b/extensions/user-theme/extension.js
@@ -58,6 +58,9 @@ class ThemeManager {
     }
 }
 
+/**
+ * @returns {ThemeManager} - the extension state object
+ */
 function init() {
     return new ThemeManager();
 }
diff --git a/extensions/user-theme/prefs.js b/extensions/user-theme/prefs.js
index b9c12fa..214da4a 100644
--- a/extensions/user-theme/prefs.js
+++ b/extensions/user-theme/prefs.js
@@ -174,9 +174,13 @@ class ThemeRow extends Gtk.ListBoxRow {
     }
 });
 
+/** */
 function init() {
 }
 
+/**
+ * @returns {Gtk.Widget} - the prefs widget
+ */
 function buildPrefsWidget() {
     return new UserThemePrefsWidget();
 }
diff --git a/extensions/user-theme/util.js b/extensions/user-theme/util.js
index e57a99f..cb000a7 100644
--- a/extensions/user-theme/util.js
+++ b/extensions/user-theme/util.js
@@ -3,6 +3,9 @@ const { GLib } = imports.gi;
 
 const fn = (...args) => GLib.build_filenamev(args);
 
+/**
+ * @returns {string[]} - an ordered list of theme directories
+ */
 function getThemeDirs() {
     return [
         fn(GLib.get_home_dir(), '.themes'),
@@ -11,6 +14,9 @@ function getThemeDirs() {
     ];
 }
 
+/**
+ * @returns {string[]} - an ordered list of mode theme directories
+ */
 function getModeThemeDirs() {
     return GLib.get_system_data_dirs()
         .map(dir => fn(dir, 'gnome-shell', 'theme'));
diff --git a/extensions/window-list/extension.js b/extensions/window-list/extension.js
index 18dee1c..fe0cb21 100644
--- a/extensions/window-list/extension.js
+++ b/extensions/window-list/extension.js
@@ -23,6 +23,10 @@ const GroupingMode = {
     ALWAYS: 2,
 };
 
+/**
+ * @param {Shell.App} app - an app
+ * @returns {number} - the smallest stable sequence of the app's windows
+ */
 function _getAppStableSequence(app) {
     let windows = app.get_windows().filter(w => !w.skip_taskbar);
     return windows.reduce((prev, cur) => {
@@ -30,7 +34,6 @@ function _getAppStableSequence(app) {
     }, Infinity);
 }
 
-
 class WindowContextMenu extends PopupMenu.PopupMenu {
     constructor(source, metaWindow) {
         super(source, 0.5, St.Side.BOTTOM);
@@ -1172,6 +1175,9 @@ class Extension {
     }
 }
 
+/**
+ * @returns {Extension} - the extension's state object
+ */
 function init() {
     return new Extension();
 }
diff --git a/extensions/window-list/prefs.js b/extensions/window-list/prefs.js
index aec8cc9..bdf834f 100644
--- a/extensions/window-list/prefs.js
+++ b/extensions/window-list/prefs.js
@@ -9,7 +9,7 @@ const Me = ExtensionUtils.getCurrentExtension();
 const Gettext = imports.gettext.domain(Me.metadata['gettext-domain']);
 const _ = Gettext.gettext;
 
-
+/** */
 function init() {
     ExtensionUtils.initTranslations();
 }
@@ -105,6 +105,9 @@ class WindowListPrefsWidget extends Gtk.Box {
     }
 });
 
+/**
+ * @returns {Gtk.Widget} - the prefs widget
+ */
 function buildPrefsWidget() {
     return new WindowListPrefsWidget();
 }
diff --git a/extensions/windowsNavigator/extension.js b/extensions/windowsNavigator/extension.js
index bb72d7b..a2cab42 100644
--- a/extensions/windowsNavigator/extension.js
+++ b/extensions/windowsNavigator/extension.js
@@ -262,6 +262,9 @@ class Extension {
     }
 }
 
+/**
+ * @returns {Extension} - the extension's state object
+ */
 function init() {
     return new Extension();
 }
diff --git a/extensions/workspace-indicator/extension.js b/extensions/workspace-indicator/extension.js
index 6974062..d8463da 100644
--- a/extensions/workspace-indicator/extension.js
+++ b/extensions/workspace-indicator/extension.js
@@ -445,17 +445,20 @@ class WorkspaceIndicator extends PanelMenu.Button {
     }
 });
 
+/** */
 function init() {
     ExtensionUtils.initTranslations();
 }
 
 let _indicator;
 
+/** */
 function enable() {
     _indicator = new WorkspaceIndicator();
     Main.panel.addToStatusArea('workspace-indicator', _indicator);
 }
 
+/** */
 function disable() {
     _indicator.destroy();
 }
diff --git a/extensions/workspace-indicator/prefs.js b/extensions/workspace-indicator/prefs.js
index 567f3e9..e5c5500 100644
--- a/extensions/workspace-indicator/prefs.js
+++ b/extensions/workspace-indicator/prefs.js
@@ -210,10 +210,14 @@ class NewWorkspaceRow extends Gtk.ListBoxRow {
     }
 });
 
+/** */
 function init() {
     ExtensionUtils.initTranslations();
 }
 
+/**
+ * @returns {Gtk.Widget} - the prefs widget
+ */
 function buildPrefsWidget() {
     return new WorkspaceSettingsWidget();
 }
[Date Prev][Date Next]   [Thread Prev][Thread Next]   [Thread Index] [Date Index] [Author Index]