Remediate JSDoc violations in plugins/learn

Adds typedef imports for Vue Ref/ComputedRef and ContentNode-family
types used in composables and progress-tracking; restores typed
@returns shapes on useCoreLearn; fills missing block descriptions,
@param descriptions, @throws, and @returns declarations across the
learn-app composables and views.

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

Author: rtibbles

kolibri/plugins/learn/frontend/apiResources.js

@@ -1,8 +1,7 @@
 import { Resource } from 'kolibri/apiResource';
 
 /**
- * Gets all of the Classrooms in which a Learner is enrolled
- *
+ * Gets all of the Classrooms in which a Learner is enrolled.
  * @example To get Classrooms without assignments and progress:
  * LearnerClassroomResource.fetchCollection({
  *   getParams: { no_assignments: true },

kolibri/plugins/learn/frontend/composables/__mocks__/useDevices.js

@@ -8,7 +8,7 @@
  * If you need to override some default values from some tests,
  * you can import a helper function `useDevicesMock` that accepts
  * an object with values to be overriden and use it together
- * with  `mockImplementation` as follows:
+ * with  `mockImplementation`, as shown in the example below.
  *
  * ```
  * // eslint-disable-next-line import-x/named

kolibri/plugins/learn/frontend/composables/__mocks__/useDownloadRequests.js

@@ -8,7 +8,7 @@
  * If you need to override some default values from some tests,
  * you can import a helper function `useDownloadRequestsMock` that accepts
  * an object with values to be overriden and use it together
- * with  `mockImplementation` as follows:
+ * with  `mockImplementation`, as shown in the example below.
  *
  * ```
  * // eslint-disable-next-line import-x/named

kolibri/plugins/learn/frontend/composables/__mocks__/useLearnerResources.js

@@ -8,7 +8,7 @@
  * If you need to override some default values from some tests,
  * you can import a helper function `useLearnerResourcesMock` that accepts
  * an object with values to be overriden and use it together
- * with  `mockImplementation` as follows:
+ * with  `mockImplementation`, as shown in the example below.
  *
  * ```
  * // eslint-disable-next-line import-x/named

kolibri/plugins/learn/frontend/composables/__mocks__/usePinnedDevices.js

@@ -8,7 +8,7 @@
  * If you need to override some default values from some tests,
  * you can import a helper function `usePinnedDevicesMock` that accepts
  * an object with values to be overriden and use it together
- * with  `mockImplementation` as follows:
+ * with  `mockImplementation`, as shown in the example below.
  *
  * ```
  * // eslint-disable-next-line import-x/named

kolibri/plugins/learn/frontend/composables/useBookmarks.js

@@ -23,16 +23,14 @@ const loadingBookmarksMap = reactive({});
 
 /**
  * Adds or updates a bookmark in the shared bookmarksMap.
- *
- * @param {Object} bookmark - A bookmark object with at least `contentnode_id` and `id`.
+ * @param {object} bookmark - A bookmark object with at least `contentnode_id` and `id`.
  */
 export function setBookmark(bookmark) {
   set(bookmarksMap, bookmark.contentnode_id, bookmark);
 }
 
 /**
  * Removes a bookmark from the shared bookmarksMap by contentnode_id.
- *
  * @param {string} contentnodeId - The content node ID to remove from the map.
  */
 export function clearBookmark(contentnodeId) {
@@ -42,7 +40,6 @@ export function clearBookmark(contentnodeId) {
 /**
  * Creates a bookmark on the server and updates the local bookmarksMap.
  * On failure, removes the entry from the map.
- *
  * @param {string} contentnodeId - The content node ID to bookmark.
  * @returns {Promise} Promise that resolves with the created bookmark data.
  */
@@ -71,7 +68,6 @@ export async function createBookmark(contentnodeId) {
 /**
  * Removes a bookmark from the server and updates the local bookmarksMap.
  * On failure, restores the bookmark back into the map.
- *
  * @param {string} contentnodeId - The content node ID whose bookmark to remove.
  * @returns {Promise} Promise that resolves when the bookmark is deleted.
  */
@@ -99,8 +95,7 @@ export async function removeBookmark(contentnodeId) {
 export default function useBookmarks() {
   /**
    * Fetches bookmarks data and saves data to this composable's store.
-   *
-   * @param {Object} getParams - Parameters to filter by (e.g. { contentnode_id }).
+   * @param {object} getParams - Parameters to filter by (e.g. { contentnode_id }).
    * @returns {Promise} Promise that resolves with the fetched bookmarks array.
    * @public
    */

kolibri/plugins/learn/frontend/composables/useContentLink.js

@@ -39,10 +39,12 @@ export default function useContentLink() {
    * A function to generate a VueRouter link object that links to
    * either a resource or a topic, and generates query parameters
    * that allow creating a backlink to the route context in which
-   * this link is generated
-   * @param {string} id - the id of the node
-   * @param {boolean} isResource - whether this is a resource or not
-   * @return {Object} VueRouter link object
+   * this link is generated.
+   * @param {string} id - The id of the node.
+   * @param {boolean} isResource - Whether this is a resource or not.
+   * @param {string} [deviceId] - Override for the device id route parameter; defaults
+   * to the device id on the current route.
+   * @returns {object} VueRouter link object.
    */
   function genContentLinkBackLinkCurrentPage(id, isResource = false, deviceId) {
     const query = _getBackLinkQuery();
@@ -69,9 +71,10 @@ export default function useContentLink() {
    * while maintaining the conceptual model of a single immersive overlay
    * that can be closed out, returning to the originating page that linked
    * to the original resource.
-   * @param {string} id - the id of the node
-   * @param {boolean} isResource - whether this is a resource or not
-   * @return {Object} VueRouter link object
+   * @param {string} id - The id of the node.
+   * @param {boolean} isResource - Whether this is a resource or not.
+   * @param {string} [deviceId] - Override for the device id route parameter.
+   * @returns {object} VueRouter link object.
    */
   function genContentLinkKeepCurrentBackLink(id, isResource = false, deviceId) {
     const oldQuery = route.query;
@@ -88,8 +91,9 @@ export default function useContentLink() {
    * while maintaining the conceptual model of a single immersive overlay
    * that can be closed out, returning to the originating page that linked
    * to the original parent topic of the resource.
-   * @param {string} id - the id of the node
-   * @return {Object} VueRouter link object
+   * @param {string} id - The id of the node.
+   * @param {string} [deviceId] - Override for the device id route parameter.
+   * @returns {object} VueRouter link object.
    */
   function genContentLinkKeepPreviousBackLink(id, deviceId) {
     const oldQuery = _decodeBackLinkQuery(route.query);

kolibri/plugins/learn/frontend/composables/useContentNodeProgress.js

@@ -32,11 +32,11 @@ export function setContentNodeProgress(progress) {
 export default function useContentNodeProgress() {
   /**
    * Fetches content node progress data
-   * and saves data to this composable's store
-   *
-   * @param {Object} getParams Parameters to filter by, should be the same as
+   * and saves data to this composable's store.
+   * @param {object} getParams - Parameters to filter by, should be the same as
    * the contentnodes fetched that we want the progress for.
-   * @returns {Promise}
+   * @returns {Promise<void>} Resolves once the progress data has been merged into
+   * the shared store.
    * @public
    */
   function fetchContentNodeProgress(getParams) {
@@ -52,12 +52,15 @@ export default function useContentNodeProgress() {
   }
 
   /**
-   * Fetches content node progress data
-   * and saves data to this composable's store
-   *
-   * @param {Object} getParams Parameters to filter by, should be the same as
+   * Fetches content node tree progress data and saves data to this composable's store.
+   * @param {object} getParams - Parameters to filter by, should be the same as
    * the contentnodes fetched that we want the progress for.
-   * @returns {Promise}
+   * @param {string} getParams.id - The id of the parent content node whose tree progress
+   * should be fetched.
+   * @param {object} getParams.params - GET parameters forwarded to the tree progress
+   * endpoint (e.g. pagination state).
+   * @returns {Promise<void>} Resolves once the progress data has been merged into
+   * the shared store.
    * @public
    */
   function fetchContentNodeTreeProgress({ id, params }) {

kolibri/plugins/learn/frontend/composables/useCoreLearn.js

@@ -4,6 +4,8 @@ import client from 'kolibri/client';
 import urls from 'kolibri/urls';
 import plugin_data from 'kolibri-plugin-data';
 
+/** @typedef {import('vue').Ref} Ref */
+
 /**
  * Whether the user is in any classes
  * @type {Ref<boolean>}
@@ -30,9 +32,11 @@ export function prepareLearnApp() {
 }
 
 /**
- * @return {{
+ * Returns the learn-app's reactive state flags for classroom membership and download
+ * permissions.
+ * @returns {{
  *   canDownloadExternally: Ref<boolean>, canAddDownloads: Ref<boolean>, inClasses: Ref<boolean>
- * }}
+ * }} Reactive learn-app state.
  */
 export default function useCoreLearn() {
   return {

kolibri/plugins/learn/frontend/composables/useDevices.js

@@ -16,8 +16,8 @@ import { KolibriStudioId } from '../constants';
 import { learnStrings } from '../views/commonLearnStrings';
 
 /**
- * The ref is defined in the outer scope so it can be used as a shared store
- * @type {Ref<NetworkLocation|null>}
+ * The ref is defined in the outer scope so it can be used as a shared store.
+ * @type {import('vue').Ref<?object>}
  */
 const currentDevice = ref(null);
 
@@ -78,9 +78,12 @@ export function setCurrentDevice(id) {
 }
 
 /**
- * @param {string|null} routingDeviceId
- * @param {function(NetworkLocation):*} callback
- * @return {ComputedRef<*|null>}
+ * Build a computed ref that runs `callback` against the current device only when
+ * the device's `instance_id` matches the routed device id.
+ * @param {import('vue').Ref<?string>} routingDeviceId - Reactive device id from the route.
+ * @param {(device: object) => unknown} callback - Selector applied to the matching device.
+ * @returns {import('vue').ComputedRef<unknown>} Computed ref returning the selector's
+ * result, or undefined when the current device is not the routed device.
  */
 function computedDevice(routingDeviceId, callback) {
   return computed(() => {