Remediate JSDoc violations in remaining plugins

Covers epub_viewer, qti_viewer, and user_auth. Strips a stray period
on a URL in qti and fills the few missing JSDoc descriptions and
@param descriptions to satisfy the new rules.

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

Author: rtibbles

kolibri/plugins/epub_viewer/frontend/views/SearchSideBar.vue

@@ -96,9 +96,9 @@
    * Searches through an entire book for a string, but caps after a certain amount of results is
    * exceeded
    * Helpful in preventing a CPU lockup for search queries with a lot of search results
-   * @param {object} book Ebookjs book object
-   * @param {string} searchQuery String to search for
-   * @param {number} maxSearchResults Stop searching for matches after this is amount is exceeded,
+   * @param {object} book - Epubjs book object
+   * @param {string} searchQuery - String to search for
+   * @param {number} maxSearchResults - Stop searching for matches after this is amount is exceeded,
    *                                  e.g. 1000
    * @returns {Promise} A promise that resolves to the search results
    */
@@ -174,6 +174,7 @@
     },
     methods: {
       /**
+       * Move keyboard focus to the search input so the user can start typing.
        * @public
        */
       focusOnInput() {
@@ -201,8 +202,8 @@
       /**
        * This method "marks" the match text to which the cfi refers in every result in the
        * search results list
-       * @param {array} searchResults
-       * @returns {array} searchResults with the excerpt split into before, match, and after
+       * @param {Array} searchResults - Raw search results returned by the epub search
+       * @returns {Array} searchResults with the excerpt split into before, match, and after
        * where the match is the text that will be highlighted
        */
       selectMatchResult(searchResults) {
@@ -232,10 +233,10 @@
        * Identify the index of the match in the result excerpt based
        * on the distance between the cfis with the next result compared to
        * the distance of the result excerpt between a match and the next match.
-       * @param {object} params
-       * @param {string[]} params.textSplit The result excerpt split by the search query
-       * @param {string} params.cfi The cfi of the current result
-       * @param {object} params.nextResult The next result
+       * @param {object} params - Arguments bundled as a single object
+       * @param {string[]} params.textSplit - The result excerpt split by the search query
+       * @param {string} params.cfi - The cfi of the current result
+       * @param {object} params.nextResult - The result that immediately follows the current one
        * @returns {number} The index of the match in the result excerpt
        * @example If there are n matches in the same result excerpt, this method will
        * return 0 if the cfi refers to the first match, 1 for the second match, etc.
@@ -266,8 +267,8 @@
        * If two matches appears in the same result excerpt then they are in the same node.
        * So, this method finds the distance between the two matches and return -1 if they are
        * not in the same node.
-       * @param {string} cfi1 The cfi of the first match
-       * @param {string} cfi2 The cfi of the second match after the first one
+       * @param {string} cfi1 - The cfi of the first match
+       * @param {string} cfi2 - The cfi of the second match after the first one
        * @returns {number} The number of characters between the two matches or -1 if they are
        * not in the same node.
        */
@@ -301,10 +302,10 @@
       /**
        * Divide the excerpt into before, match, and after based on the index of the match
        * where the match is the text that will be highlighted
-       * @param {object} params
-       * @param {string[]} params.textSplit The result excerpt split by the search query
-       * @param {string} params.excerpt The result excerpt
-       * @param {number} params.selectedIndex The index of the match in the result excerpt
+       * @param {object} params - Arguments bundled as a single object
+       * @param {string[]} params.textSplit - The result excerpt split by the search query
+       * @param {string} params.excerpt - The result excerpt
+       * @param {number} params.selectedIndex - The index of the match in the result excerpt
        * @returns {object} The excerpt divided into before, match, and after
        */
       splitExcerpt({ textSplit, excerpt, selectedIndex }) {

kolibri/plugins/epub_viewer/frontend/views/TopBar.vue

@@ -84,18 +84,21 @@
     },
     methods: {
       /**
+       * Moves keyboard focus to the table of contents button.
        * @public
        */
       focusOnTocButton() {
         this.$refs.tocButton.$el.focus();
       },
       /**
+       * Moves keyboard focus to the settings button.
        * @public
        */
       focusOnSettingsButton() {
         this.$refs.settingsButton.$el.focus();
       },
       /**
+       * Moves keyboard focus to the search button.
        * @public
        */
       focusOnSearchButton() {

kolibri/plugins/pdf_viewer/frontend/utils/event_utils.js

@@ -7,33 +7,33 @@ class EventBus {
 
   /**
    * Proxy to the Vue object that is the global dispatcher.
-   * @param {string} eventName
-   * @param {...any} args
+   * @param {string} eventName - Name of the event to emit.
+   * @param {...unknown} args - Payload arguments forwarded to listeners.
    */
   emit(eventName, ...args) {
     this._eventDispatcher.$emit(eventName, ...args);
   }
   /**
    * Proxy to the Vue object that is the global dispatcher.
-   * @param {string} event
-   * @param {function} callback
+   * @param {string} event - Name of the event to subscribe to.
+   * @param {Function} callback - Listener invoked when the event fires.
    */
   on(event, callback) {
     this._eventDispatcher.$on(event, callback);
   }
   /**
    * Proxy to the Vue object that is the global dispatcher.
    * Takes any arguments and passes them on.
-   * @param {string} event
-   * @param {function} callback
+   * @param {string} event - Name of the event to subscribe to once.
+   * @param {Function} callback - Listener invoked once when the event fires.
    */
   once(event, callback) {
     this._eventDispatcher.$once(event, callback);
   }
   /**
    * Proxy to the Vue object that is the global dispatcher.
-   * @param {string} event
-   * @param {function} callback
+   * @param {string} event - Name of the event to unsubscribe from.
+   * @param {Function} callback - The previously-subscribed listener to remove.
    */
   off(event, callback) {
     this._eventDispatcher.$off(event, callback);

kolibri/plugins/pdf_viewer/frontend/utils/text_layer_builder.js

@@ -30,14 +30,13 @@ const logging = logger.getLogger(__filename);
 const EXPAND_DIVS_TIMEOUT = 300; // ms
 
 /**
- * @typedef {Object} TextLayerBuilderOptions
- * @property {HTMLDivElement} textLayerDiv - The text layer container.
- * @property {number} pageIndex - The page index.
- * @property {PageViewport} viewport - The viewport of the text layer.
- * @property {TextHighlighter} highlighter - Optional object that will handle
- *   highlighting text from the find controller.
- * @property {boolean} enhanceTextSelection - Option to turn on improved
- *   text selection.
+ * @typedef  {object} TextLayerBuilderOptions
+ * @property {HTMLDivElement} textLayerDiv - The text layer container DOM node.
+ * @property {number} pageIndex - Zero-based PDF page index.
+ * @property {object} viewport - The pdf.js PageViewport for the text layer.
+ * @property {?object} highlighter - Optional pdf.js TextHighlighter that will handle
+ * highlighting text from the find controller.
+ * @property {boolean} enhanceTextSelection - Option to turn on improved text selection.
  */
 
 /**
@@ -71,6 +70,8 @@ class TextLayerBuilder {
   }
 
   /**
+   * Mark rendering as complete and emit `textlayerrendered` once any post-render
+   * teardown has run.
    * @private
    */
   _finishRendering() {
@@ -95,7 +96,6 @@ class TextLayerBuilder {
 
   /**
    * Renders the text layer.
-   *
    * @param {number} [timeout] - Wait for a specified amount of milliseconds
    *                             before rendering.
    */
@@ -190,7 +190,6 @@ class TextLayerBuilder {
    * Improves text selection by adding an additional div where the mouse was
    * clicked. This reduces flickering of the content if the mouse is slowly
    * dragged up or down.
-   *
    * @private
    */
   _bindMouse() {

kolibri/plugins/pdf_viewer/frontend/views/PdfRendererIndex.vue

@@ -527,6 +527,8 @@
        * - https://github.com/mozilla/pdf.js/blob/v2.14.305/web/pdf_link_service.js#L237
        * - https://github.com/mozilla/pdf.js/blob/v2.14.305/web/pdf_link_service.js#L176
        * - https://github.com/mozilla/pdf.js/blob/v2.14.305/web/base_viewer.js#L1175
+       * @param {string|Array} dest - A named destination string or an explicit
+       * destination array as defined by the PDF specification.
        */
       goToDestination(dest) {
         if (!this.pdfDocument) {
@@ -602,7 +604,11 @@
         );
       },
       /**
-       * Focus a given pdf page and return true if the page was already rendered
+       * Focus a given pdf page and return true if the page was already rendered.
+       * @param {number} pageNumber - 1-based index of the page to focus.
+       * @param {HTMLElement} bookmark - The bookmark element to return focus to
+       * when the user shift-enters out of the page.
+       * @returns {boolean} True if the page was rendered and successfully focused.
        */
       focusPage(pageNumber, bookmark) {
         const page = document.querySelector('#pdf-page-' + pageNumber);
@@ -630,6 +636,11 @@
        * Get the page number from the explicit destination array.
        * Adaptation of the original function from pdf.js:
        * - https://github.com/mozilla/pdf.js/blob/v2.14.305/web/pdf_link_service.js#L181
+       * @param {Array} explicitDest - Explicit destination array as defined by the
+       * PDF specification; the first element is either a page reference object or
+       * a numeric page index.
+       * @returns {Promise<number|undefined>} Resolves to the 1-based page number,
+       * or undefined when it cannot be determined.
        */
       getDestinationPageNumber(explicitDest) {
         return new Promise(resolve => {

kolibri/plugins/perseus_viewer/frontend/views/PerseusRendererIndex.vue

@@ -83,15 +83,17 @@
    * from the same file, but with different URLs. This also allows us to only monkey patch the Util
    * functions once, as it gives us a global register and prevents duelling components from
    * overriding each other.
-   *
-   * @type {
-   *  Object.<string, {zipFile: ZipFile, usageCounter: number, imageUrls: Object.<string, string>}>
-   * }
-   *
+   * @type {{
+   *  [key: string]: {
+   *    zipFile: ZipFile,
+   *    usageCounter: number,
+   *    imageUrls: {[key: string]: string},
+   *  },
+   * }}
    * @property {ZipFile} zipFile - A ZipFile object for the Perseus file.
    * @property {number} usageCounter - The number of components using this object.
-   * @property {Object.<string, string>} imageUrls - A lookup object mapping from the image filename
-   * to the URL generated for that image for display.
+   * @property {{[key: string]: string}} imageUrls - A lookup object mapping from the image
+   * filename to the URL generated for that image for display.
    */
   const globalPerseusFileRegistry = {};
 
@@ -601,6 +603,10 @@
         }
       },
       /**
+       * Score the current answer state through the Perseus item renderer and
+       * return the result, or null when the renderer is not yet ready.
+       * @returns {?{correct: boolean, answerState: object, simpleAnswer: string}}
+       *   The check result, or null when no answer can be checked.
        * @public
        */
       checkAnswer() {
@@ -640,6 +646,7 @@
         }
       },
       /**
+       * Reveal the next hint and emit the updated answer state.
        * @public
        */
       takeHint() {

kolibri/plugins/qti_viewer/frontend/components/AssessmentItem.vue

@@ -22,22 +22,21 @@
   import TextEntryInteraction from './interactions/TextEntryInteraction.vue';
 
   /**
-   * Extract QTI declarations of a specific type from an XML document
-   * @param {Document} xmlDocument - The QTI XML document
-   * @param {string} declarationType - 'response', 'outcome', or 'context'
-   * @param {Function} interactionHandler - a function that is called when a variable value is set
-   * @param {Ref{Object}} injectedAnswerState - a computed ref that contains any injected answers
-   * @returns {Object} Map of identifier -> QTIVariable
+   * Extract QTI declarations of a specific type from an XML document.
+   * @param {Document} xmlDocument - The QTI XML document.
+   * @param {string} declarationType - 'response', 'outcome', or 'context'.
+   * @param {Function} interactionHandler - A function called when a variable value is set.
+   * @returns {object} Map of identifier to QTIVariable.
    */
-  function getQTIDeclarations(xmlDocument, declarationType, interactionHander) {
+  function getQTIDeclarations(xmlDocument, declarationType, interactionHandler) {
     const declarations = {};
 
     const selector = `qti-${declarationType}-declaration`;
 
     const nodes = xmlDocument.querySelectorAll(selector);
 
     for (const node of nodes) {
-      const variable = new QTIVariable(node, interactionHander);
+      const variable = new QTIVariable(node, interactionHandler);
       declarations[variable.identifier] = variable;
     }
     return declarations;

kolibri/plugins/qti_viewer/frontend/components/interactions/ChoiceInteraction.vue

@@ -23,6 +23,9 @@
   /**
    * Safely normalizes a response value to an array.
    * Handles null, undefined, scalars, and arrays uniformly.
+   * @param {string|number|Array<string|number>|null|undefined} value - The QTI response
+   * value, which may be a single identifier, an array of identifiers, or empty.
+   * @returns {Array<string|number>} An array of selected identifiers (empty when value is empty).
    */
   function getSelectionsArray(value) {
     if (value === null || value === undefined) {

kolibri/plugins/qti_viewer/frontend/utils/props.js

@@ -4,28 +4,28 @@ import { coerceNumber, validateNumber, validateBoolean } from './qti/values';
 const QTI_IDENTIFIER_PATTERN = /^[a-zA-Z_][a-zA-Z0-9_-]{0,31}$/;
 
 /**
- * Validates QTI identifier format
- * @param {string|null} value - The value to validate
- * @returns {boolean} - True if valid QTI identifier or null
+ * Validates QTI identifier format.
+ * @param {string|null} value - The value to validate.
+ * @returns {boolean} - True if valid QTI identifier or null.
  */
 const validateQTIIdentifier = value => {
   return QTI_IDENTIFIER_PATTERN.test(value);
 };
 
 /**
- * Validates non-negative integer
- * @param {string|number|null} value - The value to validate
- * @returns {boolean} - True if non-negative integer or null
+ * Validates non-negative integer.
+ * @param {string|number|null} value - The value to validate.
+ * @returns {boolean} - True if non-negative integer or null.
  */
 const validateNonNegativeInt = value => {
   value = coerceNumber(value);
   return Number.isInteger(value) && value >= 0;
 };
 
 /**
- * Creates an enum validator function
- * @param {Object} enumObject - The enum object to validate against
- * @returns {Function} Validator function
+ * Creates an enum validator function.
+ * @param {object} enumObject - The enum object to validate against.
+ * @returns {Function} Validator function.
  */
 const createEnumValidator = enumObject => {
   return value => Object.values(enumObject).includes(value);
@@ -48,11 +48,11 @@ const validateOrientation = createEnumValidator(Orientation);
 
 // Common factory function for creating props
 /**
- * Creates a Vue prop configuration from a base prop object
- * @param {Object} baseProp - Base prop configuration (type, validator, etc.)
- * @param {boolean} required - Whether the prop is required (default: true)
- * @param {*} defaultValue - Default value (default: null when not required)
- * @returns {Object} Vue prop configuration
+ * Creates a Vue prop configuration from a base prop object.
+ * @param {object} baseProp - Base prop configuration (type, validator, etc.).
+ * @param {boolean} required - Whether the prop is required (default: true).
+ * @param {unknown} defaultValue - Default value (default: null when not required).
+ * @returns {object} Vue prop configuration.
  */
 const createProp = (baseProp, required = true, defaultValue) => {
   const prop = { ...baseProp };