Remediate JSDoc violations in plugins/media_player

Adds typedef import for video.js Component; restores typed @param
annotations across the videojs Vue mixins; fills missing block
descriptions, @param descriptions, and @returns declarations on
the captions/languages/transcript helper modules.

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

Author: rtibbles

kolibri/plugins/media_player/frontend/mixins/videojsButtonMixin.js

@@ -1,14 +1,20 @@
 import videojs from 'video.js';
 
 /**
- * @param {String} videojsComponent A string of the videojs component to extend
+ * Build a base class extending the named video.js menu button component, with
+ * additional behaviour for hiding the menu on mouseleave and dismissing it on
+ * outside clicks.
+ * @param {string} videojsComponent - The name of the videojs component to extend.
+ * @returns {Function} A class extending the requested videojs component.
  */
 export default function videojsButtonMixin(videojsComponent) {
   return class extends videojs.getComponent(videojsComponent) {
     /**
-     * @param player
-     * @param options
-     * @param ready
+     * Wire up the mouseleave-to-hide behaviour and the outside-click listener used
+     * to dismiss the menu.
+     * @param {object} player - The video.js player instance.
+     * @param {object} [options] - Component options forwarded to videojs.
+     * @param {Function} [ready] - Optional ready callback forwarded to videojs.
      */
     constructor(player, options, ready) {
       super(player, options, ready);
@@ -29,16 +35,18 @@ export default function videojsButtonMixin(videojsComponent) {
     }
 
     /**
-     * Should build and return an instance of a Video.js Menu
-     * @return {Menu}
+     * Should build and return an instance of a Video.js Menu. The base
+     * implementation throws; subclasses must override.
+     * @throws {Error} Always — subclasses must override this method.
      */
     buildMenu() {
       throw new Error('Not implemented');
     }
 
     /**
      * @override
-     * @return {Menu}
+     * @returns {object} A configured video.js Menu, populated with items and wired up to
+     * the outside-click listener.
      */
     createMenu() {
       if (this.items) {
@@ -65,10 +73,10 @@ export default function videojsButtonMixin(videojsComponent) {
     }
 
     /**
-     * Removes class that adds specific functionality we don't want
-     *
-     * @param {String} classNames
-     * @return {String}
+     * Removes the `vjs-menu-button-popup` class that adds specific functionality
+     * we don't want.
+     * @param {string} classNames - Space-separated class string to filter.
+     * @returns {string} The class string without the popup class.
      */
     removePopupClass(classNames) {
       return classNames.replace(/\bvjs-menu-button-popup\b/, ' ');

kolibri/plugins/media_player/frontend/mixins/videojsMenuItemVueMixin.js

@@ -1,8 +1,5 @@
 import videojsVueMixin from './videojsVueMixin';
 
-/**
- * @param {Object} vueComponent A compiled vue component object
- */
 export default function videojsMenuItemVueMixin(vueComponent) {
   return class extends videojsVueMixin('MenuItem', vueComponent) {
     createVueComponent(options = {}) {

kolibri/plugins/media_player/frontend/mixins/videojsMenuVueMixin.js

@@ -1,13 +1,20 @@
 import videojsVueMixin from './videojsVueMixin';
 
 /**
- * @param {Object} vueComponent A compiled vue component object
+ * @typedef {import('video.js').default.Component} VideoJsComponent
+ */
+
+/**
+ * Build a video.js Menu subclass that renders its content through a Vue component.
+ * @param {object} vueComponent - A compiled vue component object
+ * @returns {typeof VideoJsComponent} The extended Menu class
  */
 export default function videojsMenuVueMixin(vueComponent) {
   return class extends videojsVueMixin('Menu', vueComponent) {
     /**
-     * @param player
-     * @param options
+     * Initialise lock and focused-child state on top of the parent Menu constructor.
+     * @param {VideoJsComponent} player - The video.js player instance
+     * @param {object} [options] - Options forwarded to the parent Menu component
      */
     constructor(player, options) {
       super(player, options);
@@ -19,9 +26,8 @@ export default function videojsMenuVueMixin(vueComponent) {
     /**
      * `contentEl` is used when `addItem` is called, so this allows the addition of the text track
      * options (the languages) in the right spot
-     *
      * @override
-     * @return {*|Element}
+     * @returns {Element} The element into which menu items should be inserted
      */
     contentEl() {
       return this.getVueComponent().contentEl();
@@ -30,9 +36,8 @@ export default function videojsMenuVueMixin(vueComponent) {
     /**
      * `contentEl` is used when `addItem` is called, so this allows the addition of the text track
      * options (the languages) in the right spot
-     *
      * @override
-     * @return {*|Element}
+     * @returns {Element} The element into which menu items should be inserted
      */
     get contentEl_() {
       return this.contentEl();
@@ -44,17 +49,15 @@ export default function videojsMenuVueMixin(vueComponent) {
 
     /**
      * Override parent's method, which adds event handlers we don't want
-     *
      * @override
-     * @param {Component|String} item The name or instance of the item to add
+     * @param {VideoJsComponent | string} item - The name or instance of the item to add
      */
     addItem(item) {
       this.addChild(item);
     }
 
     /**
      * Triggered by mouseenter of button container
-     *
      * @override
      */
     show() {
@@ -63,7 +66,6 @@ export default function videojsMenuVueMixin(vueComponent) {
 
     /**
      * Triggered by mouseleave of button container
-     *
      * @override
      */
     hide() {
@@ -72,7 +74,6 @@ export default function videojsMenuVueMixin(vueComponent) {
 
     /**
      * Triggered on click in ancestor
-     *
      * @override
      */
     lockShowing() {
@@ -81,15 +82,15 @@ export default function videojsMenuVueMixin(vueComponent) {
 
     /**
      * Triggered on blur in ancestor
-     *
      * @override
      */
     unlockShowing() {
       this.doHide(true);
     }
 
     /**
-     * @param {Boolean} lock Whether or not to lock it open
+     * Show the menu, optionally locking it open so mouseleave won't hide it.
+     * @param {boolean} lock - Whether or not to lock it open
      */
     doShow(lock = false) {
       const component = this.getVueComponent();
@@ -108,7 +109,8 @@ export default function videojsMenuVueMixin(vueComponent) {
     }
 
     /**
-     * @param {Boolean} unlock Whether or not to unlock it if it's locked open
+     * Hide the menu, optionally unlocking it first if it was locked open.
+     * @param {boolean} unlock - Whether or not to unlock it if it's locked open
      */
     doHide(unlock = false) {
       const component = this.getVueComponent();
@@ -124,6 +126,8 @@ export default function videojsMenuVueMixin(vueComponent) {
 
     /**
      * Called by Video.js key event handlers
+     * @param {number} [index] - Child index to focus; defaults to the last focused child, wraps on
+     *   overflow
      */
     focus(index) {
       const children = this.children();

kolibri/plugins/media_player/frontend/mixins/videojsVueMixin.js

@@ -3,8 +3,10 @@ import store from 'kolibri/store';
 import videojs from 'video.js';
 
 /**
- * @param {String} videojsComponent A string of the videojs component to extend
- * @param {Object} vueComponent A compiled vue component object
+ * Produce a video.js component class that renders a Vue component as its DOM element.
+ * @param {string} videojsComponent - A string of the videojs component to extend
+ * @param {object} vueComponent - A compiled vue component object
+ * @returns {Function} Subclass of the named video.js component backed by the Vue component
  */
 export default function videojsVueMixin(videojsComponent, vueComponent) {
   const VideojsComponent = videojs.getComponent(videojsComponent);
@@ -14,16 +16,16 @@ export default function videojsVueMixin(videojsComponent, vueComponent) {
     /**
      * This is called by video.js code that usually constructs an element, but here we'll leverage
      * vue by calling it manually.
-     *
-     * @return {Element}
+     * @returns {Element} Root DOM element from the mounted Vue component
      */
     createEl() {
       return this.createVueComponent().$el;
     }
 
     /**
-     * @param {Object} [options]
-     * @return {VueComponent}
+     * Destroy any existing Vue instance and mount a fresh one, storing it on the component.
+     * @param {object} [options] - Extra options forwarded to the Vue component constructor
+     * @returns {VueComponent} The freshly mounted Vue component
      */
     createVueComponent(options) {
       this.clearVueComponent();
@@ -32,7 +34,8 @@ export default function videojsVueMixin(videojsComponent, vueComponent) {
     }
 
     /**
-     * @return {VueComponent}
+     * Return the currently mounted Vue component, if any.
+     * @returns {VueComponent} The currently held Vue component, or undefined if none is mounted
      */
     getVueComponent() {
       return this._vueComponent;

kolibri/plugins/media_player/frontend/modules/captions/index.js

@@ -6,7 +6,9 @@ import Settings from '../../utils/settings';
 const { handleSelectedLanguageChange } = videojs.getComponent('TextTrackMenuItem').prototype;
 
 /**
- * @return {{captionLanguage: *, captionSubtitles: boolean, captionTranscript: boolean}}
+ * Build the default captions settings, seeded from the active Vue locale.
+ * @returns {{captionLanguage: string, captionSubtitles: boolean, captionTranscript: boolean}}
+ *   The default captions settings object.
  */
 const defaultSettings = () => ({
   captionLanguage: vue.locale,
@@ -15,16 +17,18 @@ const defaultSettings = () => ({
 });
 
 /**
- * @param state
- * @return {TextTrack[]}
+ * Resolve the captions module's track list to a plain array.
+ * @param {object} state - The captions module's Vuex state.
+ * @returns {TextTrack[]} The configured text tracks, or an empty array when none.
  */
 const tracks = state => {
   return trackUtils.listToArray(state.trackList || []);
 };
 
 /**
- * @param state
- * @return {TextTrack|null}
+ * Find the track matching the active captions language.
+ * @param {object} state - The captions module's Vuex state.
+ * @returns {?TextTrack} The matching track, or undefined when no track matches.
  */
 const languageTrack = state => {
   return tracks(state).find(track => state.language === track.language);
@@ -81,28 +85,32 @@ export default {
   },
   getters: {
     /**
-     * @param state
-     * @return {string}
+     * The display label for the track matching the active captions language.
+     * @param {object} state - The captions module's Vuex state.
+     * @returns {string} The matching track label, or empty string when none matches.
      */
     languageLabel(state) {
       const track = languageTrack(state);
       return track ? track.label : '';
     },
     /**
-     * @param state
-     * @return {TextTrack[]}
+     * Resolve the captions module's track list to a plain array.
+     * @param {object} state - The captions module's Vuex state.
+     * @returns {TextTrack[]} The configured text tracks.
      */
     tracks,
     /**
-     * @param state
-     * @return {TextTrack}
+     * Find the currently enabled text track.
+     * @param {object} state - The captions module's Vuex state.
+     * @returns {?TextTrack} The enabled track, or undefined when none is enabled.
      */
     activeTrack(state) {
       return tracks(state).find(track => trackUtils.isEnabled(track));
     },
     /**
-     * @param state
-     * @return {TextTrack|null}
+     * Find the track matching the active captions language.
+     * @param {object} state - The captions module's Vuex state.
+     * @returns {?TextTrack} The matching track, or undefined when no track matches.
      */
     languageTrack,
   },

kolibri/plugins/media_player/frontend/utils/track.js

@@ -4,8 +4,9 @@ export const MODE_DISABLED = 'disabled';
 
 export default {
   /**
-   * @param {String} mode
-   * @return {boolean}
+   * Check whether a track mode counts as enabled (showing or hidden).
+   * @param {string} mode - The TextTrack mode string to check
+   * @returns {boolean} True if the mode is showing or hidden
    */
   isEnabledMode(mode) {
     return mode === MODE_SHOWING || mode === MODE_HIDDEN;
@@ -14,10 +15,9 @@ export default {
   /**
    * Setting mode can cause events, which could cause loop if we don't make sure that the mode
    * isn't already the mode we're going to set
-   *
-   * @param {TextTrack} track
-   * @param {Boolean} enabled
-   * @param {Boolean} [hidden]
+   * @param {TextTrack} track - The track to update
+   * @param {boolean} enabled - Whether the track should be enabled
+   * @param {boolean} [hidden] - If enabled, whether to hide the track's cues
    */
   setMode(track, enabled, hidden = false) {
     let mode = MODE_DISABLED;
@@ -32,8 +32,9 @@ export default {
   },
 
   /**
-   * @param {TextTrack} track
-   * @return {boolean}
+   * Check whether a track is currently enabled.
+   * @param {TextTrack} track - The track to check
+   * @returns {boolean} True if the track's mode is showing or hidden
    */
   isEnabled(track) {
     return this.isEnabledMode(track.mode);
@@ -42,9 +43,8 @@ export default {
   /**
    * Text track lists do not implement all array-like features, so this will convert it into an
    * array
-   *
-   * @param {TextTrackList|TextTrackCueList} list
-   * @return {TextTrack[]|TextTrackCue[]}
+   * @param {TextTrackList|TextTrackCueList} list - The list-like object to convert
+   * @returns {TextTrack[]|TextTrackCue[]} A plain array of the list's entries
    */
   listToArray(list) {
     return Array.prototype.slice.call(list, 0);

kolibri/plugins/media_player/frontend/views/MediaPlayerCaptions/SubtitlesMenuItem.vue

@@ -29,6 +29,7 @@
     methods: {
       ...mapActions('mediaPlayer/captions', ['toggleSubtitles']),
       /**
+       * Accessible via parent component refs.
        * @public
        */
       focus() {

kolibri/plugins/media_player/frontend/views/MediaPlayerCaptions/TranscriptMenuItem.vue

@@ -34,6 +34,7 @@
     methods: {
       ...mapActions('mediaPlayer/captions', ['toggleTranscript']),
       /**
+       * Accessible via parent component refs.
        * @public
        */
       focus() {