Remediate JSDoc violations in plugins/setup_wizard and plugins/facility

Restores the importLodUsers TODO comment and merged punctuation in
wizardMachine; restores the UseActionWithUndoObject typedef and the
unmounted-component warning paragraph on useActionWithUndo; restores
the "Needed: id, facility, role" caller hint in userManagement
actions. 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/facility/frontend/composables/useActionWithUndo.js

@@ -2,31 +2,30 @@ import { bulkUserManagementStrings } from 'kolibri-common/strings/bulkUserManage
 import useSnackbar from 'kolibri/composables/useSnackbar';
 
 /**
- *
- * @param {Object} options
+ * @typedef {object} UseActionWithUndoObject
+ * @property {() => Promise<void>} performAction - A method to manually trigger the main action
+ *   with all the undo machinery set up.
+ */
+
+/**
+ * Wraps an action with an undo snackbar, providing a `performAction` function that runs the
+ * action and shows a snackbar with an undo option when it succeeds.
+ * @param {object} options - Options object.
  * @param {() => Promise<boolean>} options.action - Callback that executes the action to perform.
- * Should return a boolean promise indicating whether the action was successful. If the action
- * succeeds, the snackbar will display a success message and provide an undo option.
- *
+ *   Should return a boolean promise indicating whether the action was successful. If the action
+ *   succeeds, the snackbar will display a success message and provide an undo option.
  * @param {() => string} options.actionNotice$ - Function that returns the message to display on
- * the snackbar when the action is successful.
- *
- * @param {() => Promise<void>} options.undoAction - Callback that executes the undo action.
- * Be careful if this action is happening after the component that triggered the original action has
- * been unmounted (e.g. you cannot emit events from an unmounted component). If the undoAction fails
- * the function should throw an error, and a snackbar will be shown with a generic error message.
- *
- * @param {() => string} options.undoActionNotice$ - Function that returns the message to display on
- * the snackbar when the undo action is successful.
- *
+ *   the snackbar when the action is successful.
+ * @param {() => Promise<void>} options.undoAction - Callback that executes the undo action. Be
+ *   careful if this action is happening after the component that triggered the original action
+ *   has been unmounted (e.g. you cannot emit events from an unmounted component). If the
+ *   undoAction fails the function should throw an error, and a snackbar will be shown with a
+ *   generic error message.
+ * @param {() => string} options.undoActionNotice$ - Function that returns the message to display
+ *   on the snackbar when the undo action is successful.
  * @param {() => void} [options.onBlur] - Optional callback that executes when the undo button in
- * the snackbar loses focus.
- *
- * @typedef {Object} UseActionWithUndoObject
- * @property {() => Promise<void>} performAction - A method to manually trigger the main action
- * with all the undo machinery set up.
- *
- * @returns {UseActionWithUndoObject}
+ *   the snackbar loses focus.
+ * @returns {UseActionWithUndoObject} Undo-wrapped action helpers.
  */
 export default function useActionWithUndo({
   action,

kolibri/plugins/facility/frontend/composables/useFacilityEditor.js

@@ -9,7 +9,58 @@ import { OptionsForSignIn, PicturePasswordIconStyle } from 'kolibri-common/const
 import useFacility from 'kolibri-common/composables/useFacility';
 
 /**
- * A composable for editing facility settings and configuration
+ * @typedef {object} UseFacilityEditorReturn
+ * @property {import('vue').ComputedRef<string>} facilityId - The id of the facility being edited
+ * @property {import('vue').Ref<string>} facilityDatasetId - The dataset id used when saving
+ *   config and PIN changes
+ * @property {import('vue').Ref<string>} facilityName - The editable facility name
+ * @property {import('vue').Ref<object>} settings - The live facility config being edited
+ * @property {import('vue').Ref<object>} settingsCopy - A snapshot of settings used to detect
+ *   unsaved changes
+ * @property {import('vue').Ref<boolean>} isFacilityPinValid - Whether the entered facility PIN is
+ *   valid
+ * @property {import('vue').Ref<boolean>} facilityDataLoading - Whether facility data is loading
+ * @property {import('vue').Ref<string|null>} pictureLoginTaskId - The id of the in-progress picture
+ *   login settings task, or null
+ * @property {import('vue').ComputedRef<object>} facility - The selected facility
+ * @property {import('vue').ComputedRef<boolean>} settingsHaveChanged - Whether settings differ from
+ *   the saved snapshot
+ * @property {import('vue').ComputedRef<string|null>} isPinSet - The configured PIN code, or null
+ *   when none is set
+ * @property {import('vue').ComputedRef<boolean>} isAttendanceFeatureEnabled - Whether the
+ *   attendance feature is enabled
+ * @property {import('vue').ComputedRef<boolean>} isPictureLoginFeatureEnabled - Whether picture
+ *   login is enabled
+ * @property {import('vue').WritableComputedRef<string>} signInOption - The selected sign-in option
+ * @property {import('vue').ComputedRef<string[]>} signInOptions - The available sign-in options
+ * @property {import('vue').ComputedRef<object|null>} picturePasswordSettings - The picture password
+ *   settings, or null when not enabled
+ * @property {import('vue').WritableComputedRef<string|undefined>} picturePasswordStyle - The
+ *   picture password icon style
+ * @property {import('vue').WritableComputedRef<boolean|undefined>} picturePasswordShowIconText -
+ *   Whether picture password icons show their text labels
+ * @property {() => Promise<void>} fetchFacility - Refetches the facility and its config
+ * @property {(name: string, value: unknown) => void} modifySetting - Sets a facility config field
+ * @property {(value: string) => void} modifySignInOption - Applies the chosen sign-in option
+ * @property {(name: string, value: unknown) => void} modifyPicturePasswordSetting - Sets a picture
+ *   password setting field
+ * @property {(newExtraFields: object) => void} modifyExtraFields - Replaces the config's
+ *   extra_fields
+ * @property {() => void} copySettings - Snapshots the current settings into settingsCopy
+ * @property {() => void} undoSettingsChange - Restores settings from the snapshot
+ * @property {() => void} resetState - Resets all editor state to initial values
+ * @property {(name: string) => Promise<object>} saveFacilityName - Saves a new facility name
+ * @property {() => Promise<void>} saveFacilityConfig - Persists the facility config
+ * @property {(payload: object) => Promise<void>} setPin - Sets the facility PIN
+ * @property {() => Promise<void>} unsetPin - Clears the facility PIN
+ * @property {(loading: boolean) => void} setLoading - Sets the facility data loading flag
+ * @property {() => Promise<object>} saveFacilityLoginSettings - Persists the login and picture
+ *   password settings
+ */
+
+/**
+ * Composable providing facility editor state and actions for the facility settings page.
+ * @returns {UseFacilityEditorReturn} Facility editor state, computed properties, and action methods
  */
 export default function useFacilityEditor() {
   const {
@@ -140,9 +191,9 @@ export default function useFacilityEditor() {
   }
 
   /**
-   * Updates the facility's name
-   * @param {string} name
-   * @return {Promise<*>}
+   * Saves a new facility name to the backend and refreshes the facilities list.
+   * @param {string} name - The new facility name to save.
+   * @returns {Promise<object>} Resolves with the updated facility model.
    */
   async function saveFacilityName(name) {
     const facility = await FacilityResource.saveModel({

kolibri/plugins/facility/frontend/composables/usePagination.js

@@ -4,8 +4,11 @@ import pickBy from 'lodash/pickBy';
 import clamp from 'lodash/clamp';
 
 /**
- * Composable for managing pagination state and navigation
- * Handles page changes, items per page, and URL query synchronization
+ * Composable providing pagination state and navigation for the users table.
+ * @param {object} options - Options object.
+ * @param {object} options.usersCount - A ref or computed with the total number of users.
+ * @param {object} options.totalPages - A ref or computed with the total number of pages.
+ * @returns {object} Pagination state and navigation methods.
  */
 export default function usePagination({ usersCount, totalPages } = {}) {
   const route = useRoute();

kolibri/plugins/facility/frontend/composables/useUsersFilters.js

@@ -10,10 +10,21 @@ import { DateRangeFilters } from '../constants';
 
 /**
  * Composable to manage user filters in the user management pages.
- *
- * @param {object} options
- * @param {Array} options.classes - Ref to the list of classes available for filtering.
- * @returns
+ * @param {object} options - Composable options.
+ * @param {import('vue').Ref<Array<{id: string, name: string}>>} options.classes - Ref to the
+ * list of classes available for filtering.
+ * @returns {{
+ *   routeFilters: import('vue').ComputedRef<object>,
+ *   workingFilters: object,
+ *   numAppliedFilters: import('vue').ComputedRef<number>,
+ *   classesOptions: import('vue').ComputedRef<Array<{id: string, label: string}>>,
+ *   userFilterOptions: Array<{id: string, label: string, icon: string}>,
+ *   creationDateOptions: Array<{value: string, label: string, dateSubtraction?: object}>,
+ *   applyFilters: (options?: {nextRouteName?: string}) => void,
+ *   resetFilters: () => void,
+ *   getBackendFilters: () => object,
+ *   resetWorkingFilters: () => void,
+ * }} The user-filter state, options, and methods.
  */
 export default function useUsersFilters({ classes }) {
   const router = useRouter();
@@ -134,10 +145,9 @@ export default function useUsersFilters({ classes }) {
    * Apply the current filters to the route by updating the query parameters,
    * and pushing the new route. This will remove from the query any filters
    * that are not longer applied, but will leave any other query parameters intact.
-   *
-   * @param {object} options
-   * @param {string} options.nextRouteName - The name of the route to navigate to
-   *                                         after applying filters.
+   * @param {object} [options] - Routing overrides applied alongside the new query.
+   * @param {string} [options.nextRouteName] - The name of the route to navigate to
+   * after applying filters; defaults to the current route name.
    */
   const applyFilters = ({ nextRouteName } = {}) => {
     const nextQuery = { ...route.query };

kolibri/plugins/facility/frontend/composables/useUsersTableSearch.js

@@ -4,8 +4,8 @@ import pickBy from 'lodash/pickBy';
 import debounce from 'lodash/debounce';
 
 /**
- * Composable for managing search functionality in the Users table
- * Handles search term state and URL query parameter synchronization
+ * Composable providing search state and methods for the facility users table.
+ * @returns {object} Search term ref, textbox ref, and methods to focus and clear the search.
  */
 export default function useUsersTableSearch() {
   const route = useRoute();

kolibri/plugins/facility/frontend/modules/classEditManagement/actions.js

@@ -46,9 +46,12 @@ export function removeClassCoach(store, { classId, userId }) {
 }
 
 /**
- * Do a PATCH to update the class.
- * @param {string} id - class id.
- * @param {object} updateData.
+ * Updates a class with the given data and commits the change to the store.
+ * @param {object} store - The Vuex store instance.
+ * @param {object} payload - Payload object.
+ * @param {string} payload.id - The ID of the class to update.
+ * @param {object} payload.updateData - The data to update on the class.
+ * @returns {Promise<void>|void} Resolves when the class has been updated.
  */
 export function updateClass(store, { id, updateData }) {
   if (!id || Object.keys(updateData).length === 0) {

kolibri/plugins/facility/frontend/modules/classManagement/actions.js

@@ -3,8 +3,10 @@ import { handleApiError } from 'kolibri/utils/appError';
 import { selectedFacilityId } from 'kolibri-common/composables/useFacility';
 
 /**
- * Do a POST to create new class
- * @param {string} name
+ * Creates a new class with the given name and adds it to the store.
+ * @param {object} store - The Vuex store instance.
+ * @param {string} name - The name for the new class.
+ * @returns {Promise<void>} Resolves when the class has been created.
  */
 export function createClass(store, name) {
   return ClassroomResource.saveModel({

kolibri/plugins/facility/frontend/modules/userManagement/actions.js

@@ -5,12 +5,11 @@ import { selectedFacilityId } from 'kolibri-common/composables/useFacility';
 import { updateFacilityLevelRoles } from './utils';
 
 /**
- * Does a POST request to assign a user role (only used in this file)
- * @param {Object} user
- * @param {string} user.id
- * @param {string} user.facility
- * @param {string} user.roles
- * Needed: id, facility, role
+ * Does a POST request to assign a user role (only used in this file). Needed fields on `user`:
+ * `id`, `facility`.
+ * @param {object} user - The facility user object.
+ * @param {object} role - The role object; `role.kind` is the role kind to assign.
+ * @returns {Promise<object>} Resolves with the refreshed user model.
  */
 function setUserRole(user, role) {
   return updateFacilityLevelRoles(user, role.kind).then(() => {
@@ -20,9 +19,11 @@ function setUserRole(user, role) {
 }
 
 /**
- * Do a POST to create new user
- * @param {object} stateUserData
- *  Needed: username, full_name, facility, role, password
+ * Does a POST to create a new facility user. Needed fields on `payload`: `username`, `full_name`,
+ * `facility`, `role`, `password`.
+ * @param {object} store - The Vuex store instance.
+ * @param {object} payload - User creation data: username, password, role, and demographics.
+ * @returns {Promise<object|void>} Resolves when the user has been created.
  */
 export function createFacilityUser(store, payload) {
   return FacilityUserResource.saveModel({

kolibri/plugins/facility/frontend/modules/userManagement/utils.js

@@ -5,12 +5,15 @@ import RoleResource from 'kolibri-common/apiResources/RoleResource';
 const FACILITY_ROLES = [UserKinds.ADMIN, UserKinds.ASSIGNABLE_COACH, UserKinds.COACH];
 
 /**
- * Implements business logic for changing a FacilityUser's Role
- *
- * If Learner/New User -> ASSIGNABLE_COACH/COACH/ADMIN, then create that Role
- * If ASSIGNABLE_COACH/COACH/ADMIN -> LEARNER, then delete all Classroom-Level Coach Roles
- * IF ASSIGNABLE_COACH/COACH/ADMIN -> ASSIGNABLE_COACH/COACH/ADMIN, then replace only that Role
+ * Implements business logic for changing a FacilityUser's Role.
  *
+ * If Learner/New User -> ASSIGNABLE_COACH/COACH/ADMIN, then create that Role.
+ * If ASSIGNABLE_COACH/COACH/ADMIN -> LEARNER, then delete all Classroom-Level Coach Roles.
+ * IF ASSIGNABLE_COACH/COACH/ADMIN -> ASSIGNABLE_COACH/COACH/ADMIN, then replace only that Role.
+ * @param {object} facilityUser - The user whose facility-level role is being updated.
+ * @param {string} newRoleKind - The desired UserKinds value for the user's facility role.
+ * @returns {Promise<unknown>|undefined} Promise resolving once the role updates have
+ * been persisted, or undefined when no transition is supported by this helper.
  */
 export function updateFacilityLevelRoles(facilityUser, newRoleKind) {
   const { roles, facility, id } = facilityUser;

kolibri/plugins/setup_wizard/frontend/api.js

@@ -5,8 +5,8 @@ import { Resource } from 'kolibri/apiResource';
 /**
  * The <Module>Resource classes here map directly to the <Module>ViewSet of the same
  * name in the kolibri.plugins.setup_wizard.api module (note how the definitions of)
- * the Resource instances below have 'kolibri.plugins.setup_wizard' for their 'namespace'
- **/
+ * the Resource instances below have 'kolibri.plugins.setup_wizard' for their 'namespace'.
+ */
 
 export const SetupWizardResource = new Resource({
   name: 'setupwizard',