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

@@ -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();
 }

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();

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();
 }

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();
 }

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;
 }

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;
 

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();
 }

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');

extensions/user-theme/extension.js

@@ -58,6 +58,9 @@ class ThemeManager {
     }
 }
 
+/**
+ * @returns {ThemeManager} - the extension state object
+ */
 function init() {
     return new ThemeManager();
 }

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();
 }

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'));

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();
 }

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();
 }

extensions/windowsNavigator/extension.js

@@ -262,6 +262,9 @@ class Extension {
     }
 }
 
+/**
+ * @returns {Extension} - the extension's state object
+ */
 function init() {
     return new Extension();
 }

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();
 }

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();
 }