Remediate JSDoc violations in plugins/device

Restores the HACK note in availableChannelsActions explaining the
unlisted-channel workaround; restores Node/SelectedNodes/AnnotatedNode
typedefs in treeViewUtils; restores the downloadChannelMetadata
JSDoc and the "does not interact with Vuex store" caveat in wizard
utils. Fills missing block descriptions, @param descriptions,
@throws, and @returns declarations.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

Author: rtibbles

kolibri/plugins/device/frontend/modules/deviceInfo/handlers.js

@@ -37,10 +37,10 @@ export function getDeviceInfo() {
 }
 
 /**
- * Action to hydrate device-info page.
- *
- * @param {Store} store
- * @returns Promise<void>
+ * Fetches device info and commits it to the Vuex store for the device info page.
+ * @param {object} store - The Vuex store instance.
+ * @param {object} route - The current Vue Router route object.
+ * @returns {Promise<void>} Resolves when device info has been loaded into the store.
  */
 export function showDeviceInfoPage(store, route) {
   const { canManageContent } = useUser();

kolibri/plugins/device/frontend/modules/manageContent/utils.js

@@ -3,10 +3,11 @@ import { TaskStatuses } from 'kolibri-common/utils/syncTaskUtils';
 
 /**
  * Watches the state.taskList and resolves when the tracked Task is COMPLETED.
- *
- * @param {string} taskId
- * @returns {Promise}
- *
+ * @param {string} taskId - The id of the task to track.
+ * @param {object} [store] - The Vuex store to watch (defaults to the core store).
+ * @returns {Promise<{taskId: string, cancelled: boolean}>} Resolves when the task
+ * completes (or is cancelled, in which case `cancelled` is true). Rejects when the
+ * task transitions to a failed state.
  */
 export function waitForTaskToComplete(taskId, store = coreStore) {
   const taskList = state => state.manageContent.taskList;

kolibri/plugins/device/frontend/modules/userPermissions/actions.js

@@ -3,11 +3,10 @@ import FacilityUserResource from 'kolibri-common/apiResources/FacilityUserResour
 import { handleApiError } from 'kolibri/utils/appError';
 
 /**
- * Adds or modifies a DevicePermissions model.
- *
- * @param {boolean} payload.is_superuser
- * @param {boolean} payload.can_manage_content
- * @returns Promise<DevicePermissions>
+ * Saves or updates device permissions for a user and commits the updated state to the store.
+ * @param {object} store - The Vuex store instance.
+ * @param {object} payload - Permissions payload with userId, is_superuser, and can_manage_content.
+ * @returns {Promise<object>} Resolves with the updated user model.
  */
 export function addOrUpdateUserPermissions(store, payload) {
   const permissions = {

kolibri/plugins/device/frontend/modules/userPermissions/handlers.js

@@ -8,11 +8,11 @@ import { handleApiError } from 'kolibri/utils/appError';
 import { pageLoading } from 'kolibri-common/composables/usePageLoading';
 
 /**
- * Serially fetches Permissions, then FacilityUser. If returned Promise rejects,
- * it is from the request for FacilityUser.
- *
- * @param {string} userId
- * @returns Promise<{ permissions, user }, FacilityUserError>
+ * Serially fetches Permissions, then FacilityUser. If the returned Promise rejects, it
+ * is from the request for FacilityUser.
+ * @param {string} userId - The ID of the user to fetch permissions for.
+ * @returns {Promise<{permissions: object, user: object}>} Resolves with combined
+ *   permissions and user data.
  */
 function fetchUserPermissions(userId) {
   const permissionsPromise = DevicePermissionsResource.fetchModel({ id: userId, force: true });
@@ -39,11 +39,11 @@ function fetchUserPermissions(userId) {
 }
 
 /**
- * Action to hydrate user-permissions-page.
- *
- * @param {Store} store
- * @param {string} userId
- * @returns Promise<void>
+ * Load the user permissions page state into the Vuex store.
+ * @param {object} store - The Vuex store instance.
+ * @param {string} userId - The ID of the user whose permissions to display.
+ * @param {object} route - The current Vue Router route object.
+ * @returns {Promise<void>} Resolves when state has been loaded.
  */
 export function showUserPermissionsPage(store, userId, route) {
   const { fetchFacilities } = useFacilities();

kolibri/plugins/device/frontend/modules/wizard/actions/availableChannelsActions.js

@@ -2,14 +2,19 @@ import differenceBy from 'lodash/differenceBy';
 import find from 'lodash/find';
 import { getRemoteChannelByToken } from '../utils';
 
+/**
+ * @typedef {import('kolibri-common/apiResources/RemoteChannelResource').Channel} Channel
+ */
+
 /**
  * HACK: Makes a request to Kolibri Studio to get info on unlisted channels, then appends
- * them to the public channels. This hack is to get around the fact that the ChannelMetadata object
- * does not indicate the origins of a channel: whether a remote public, remote unlisted, or bespoke
- * channel from USB, the ChannelMetadata is identical.
- *
- * @param {Array<Channel>} publicChannels - the list of publich channels, which will not be queried
- * @returns {Promise<Array<Channel>>}
+ * them to the public channels. This hack is to get around the fact that the ChannelMetadata
+ * object does not indicate the origins of a channel: whether a remote public, remote unlisted,
+ * or bespoke channel from USB, the ChannelMetadata is identical.
+ * @param {object} store - The Vuex store instance.
+ * @param {Array<Channel>} publicChannels - The list of public channels, which will not be
+ *   queried.
+ * @returns {Promise<Array<Channel>>} Resolves with the combined channel list.
  */
 export function getAllRemoteChannels(store, publicChannels) {
   const { channelList } = store.rootState.manageContent;

kolibri/plugins/device/frontend/modules/wizard/actions/contentTreeViewerActions.js

@@ -12,11 +12,9 @@ function isDescendantOrSelf(testNode, selfNode) {
 }
 
 /**
- * Queries the server for the current total file size and resource count
- * and then sets it to the store.
- *
- * @returns {Promise}
- *
+ * Fetches and commits the file size and resource count for the current transfer selection.
+ * @param {object} store - The Vuex store instance with transfer state.
+ * @returns {Promise<void>} Resolves when the transfer size has been updated in the store.
  */
 function setImportExportFileSizeAndResourceCount(store) {
   const { transferredChannel, nodesForTransfer } = store.state;
@@ -59,11 +57,10 @@ function setImportExportFileSizeAndResourceCount(store) {
 }
 
 /**
- * Adds a new node to the transfer list.
- *
- * @param node {Node} - Node to be added
- * @param node.path {Array<String>} - path (via ids) from channel root to the Node
- *
+ * Adds a content node to the transfer include list and updates the transfer size.
+ * @param {object} store - The Vuex store instance with transfer state.
+ * @param {object} node - The content node to add to the transfer.
+ * @returns {Promise<void>} Resolves when the node has been added and transfer size updated.
  */
 export function addNodeForTransfer(store, node) {
   const { included, omitted } = store.state.nodesForTransfer;
@@ -84,10 +81,10 @@ export function addNodeForTransfer(store, node) {
 }
 
 /**
- * Removes node from transfer list
- *
- * @param node {Node} - node to be removed
- *
+ * Removes a content node from the transfer include list and updates the transfer size.
+ * @param {object} store - The Vuex store instance with transfer state.
+ * @param {object} node - The content node to remove from the transfer.
+ * @returns {Promise<void>} Resolves when the node has been removed and transfer size updated.
  */
 export function removeNodeForTransfer(store, node) {
   const forImport = !store.getters.inExportMode;

kolibri/plugins/device/frontend/modules/wizard/actions/selectContentActions.js

@@ -4,8 +4,9 @@ import { downloadChannelMetadata } from '../utils';
 import { getChannelWithContentSizes } from '../apiChannelMetadata';
 
 /**
- * Transitions the import/export wizard to the 'load-channel-metadata' interstitial state
- *
+ * Loads channel metadata for the current transfer, downloading it if needed.
+ * @param {object} store - The Vuex store instance with wizard state.
+ * @returns {Promise<void>} Resolves when channel metadata has been loaded into the store.
  */
 export function loadChannelMetadata(store) {
   let dbPromise;
@@ -48,13 +49,9 @@ export function loadChannelMetadata(store) {
 }
 
 /**
- * Makes a call to freespace API and places result in the store.
- * If transfer type is LOCALEXPORT, it gets the selected drive's freespace.
- *
- * @param {string} path - Path to the Kolibri data folder.
- * If empty, defaults to server's KOLIBRI_HOME.
- * @returns {Promise}
- *
+ * Gets the available free space on a drive, or on the device's content storage if no drive given.
+ * @param {object} selectedDrive - Optional drive object with a freespace property.
+ * @returns {Promise<number>} Resolves with the available free space in bytes, or -1 on error.
  */
 export function getAvailableSpaceOnDrive(selectedDrive) {
   if (selectedDrive) {

kolibri/plugins/device/frontend/modules/wizard/handlers.js

@@ -143,8 +143,10 @@ export function showAvailableChannelsPage(store, params, route) {
 }
 
 /**
- * Handler for going to Select Content Page URL directly
- * params are { channel_id: string, drive_id?: string, address_id? },
+ * Loads the select content page state for a given channel and transfer type.
+ * @param {object} store - The Vuex store instance.
+ * @param {object} params - Route params with drive_id, address_id, and channel_id.
+ * @returns {Promise<void>} Resolves when the select content page state is ready.
  */
 export function showSelectContentPage(store, params) {
   let selectedDrivePromise = Promise.resolve({});
@@ -255,10 +257,10 @@ export function showSelectContentPage(store, params) {
 }
 
 /**
- * Updates wizardState.treeView when a new topic is clicked.
- *
- * @param {Object} topic - { id, title, path }
- *
+ * Fetches granular content node data for a topic and updates the wizard tree view.
+ * @param {object} store - The Vuex store instance with wizard state.
+ * @param {object} topic - The topic content node object with id and title.
+ * @returns {Promise<void>} Resolves when the tree view topic has been updated in the store.
  */
 export function updateTreeViewTopic(store, topic) {
   const fetchArgs = {};

kolibri/plugins/device/frontend/modules/wizard/utils.js

@@ -8,11 +8,10 @@ import { waitForTaskToComplete } from '../manageContent/utils';
 import { getChannelWithContentSizes } from './apiChannelMetadata';
 
 /**
- * Makes request to RemoteChannel API with a token. Does not actually interact
- * with Vuex store.
- *
- * @param {string} token -
- * @returns Promise
+ * Makes a request to the RemoteChannel API with a token. Does not actually interact with
+ * the Vuex store.
+ * @param {string} token - The channel token to look up.
+ * @returns {Promise<object>} Resolves with the remote channel object.
  */
 export function getRemoteChannelByToken(token) {
   return RemoteChannelResource.fetchModel({ id: token, force: true });
@@ -23,10 +22,13 @@ export function getRemoteChannelBundleByToken(token) {
 }
 
 /**
- * Starts Task that downloads a Channel Metadata database.
- * NOTE: cannot be normally dispatched as an action, since it uses
- * waitForTaskToComplete (which relies on the store singleton with a .watch method)
+ * Starts a task that downloads a Channel Metadata database.
  *
+ * NOTE: cannot be normally dispatched as an action, since it uses `waitForTaskToComplete`
+ * (which relies on the store singleton with a `.watch` method).
+ * @param {object} store - The Vuex store instance; defaults to the core store singleton.
+ * @returns {Promise<object>} Resolves with the channel content sizes when the task completes.
+ * @throws {Error} If the wizard is not in an import mode when called.
  */
 export function downloadChannelMetadata(store = coreStore) {
   if (

kolibri/plugins/device/frontend/views/ManageContentPage/ManageChannelContentsPage/index.vue

@@ -316,8 +316,8 @@
         this.shownModal = null;
       },
       /**
+       * Refreshes the page data after a watched content task completes, handling channel deletion.
        * @public
-       * Used by the taskNotificationMixin to handle the completion of the task
        */
       onWatchedTaskFinished() {
         // clear out the nodeCache