Add some missing jsdoc comments, add jsdoc eslint plugin

.github/dependabot.yml

@@ -20,6 +20,7 @@ updates:
           - "@eslint/*"
           - "yaml-eslint-parser"
           - "vue-eslint-parser"
+          - "neostandard"
       stylelint:
         patterns:
           - "stylelint"

_scripts/ProcessLocalesPlugin.js

@@ -26,11 +26,11 @@ class ProcessLocalesPlugin {
     }
     this.outputDir = options.outputDir
 
-    /** @type {Map<str, any>} */
+    /** @type {Map<string, any>} */
     this.locales = new Map()
     this.localeNames = []
 
-    /** @type {Map<str, any>} */
+    /** @type {Map<string, any>} */
     this.cache = new Map()
 
     this.filePaths = []

_scripts/getShakaLocales.js

@@ -32,7 +32,7 @@ function getMappings(shakaLocales, freeTubeLocales) {
    * @type {[string, string][]}
    * Using this structure as it gets passed to `new Map()` in the player component
    * The first element is the FreeTube locale, the second one is the shaka-player one
-   **/
+   */
   const mappings = []
 
   for (const locale of freeTubeLocales) {

eslint.config.mjs

@@ -10,6 +10,7 @@ import eslintPluginJsonc from 'eslint-plugin-jsonc'
 import eslintPluginYml from 'eslint-plugin-yml'
 import yamlEslintParser from 'yaml-eslint-parser'
 import neostandard from 'neostandard'
+import jsdoc from 'eslint-plugin-jsdoc'
 
 import activeLocales from './static/locales/activeLocales.json' with { type: 'json' }
 
@@ -40,6 +41,7 @@ export default [
     ],
     plugins: {
       unicorn: eslintPluginUnicorn,
+      jsdoc,
     },
 
     languageOptions: {
@@ -115,6 +117,15 @@ export default [
       '@intlify/vue-i18n/no-deprecated-tc': 'off',
       'vue/require-explicit-emits': 'error',
       'vue/no-unused-emit-declarations': 'error',
+
+      'jsdoc/check-alignment': 'error',
+      'jsdoc/check-property-names': 'error',
+      'jsdoc/check-param-names': 'error',
+      'jsdoc/check-syntax': 'error',
+      'jsdoc/check-template-names': 'error',
+      'jsdoc/check-types': 'error',
+      'jsdoc/no-bad-blocks': 'error',
+      'jsdoc/no-multi-asterisks': 'error',
     },
   },
 

package.json

@@ -91,6 +91,7 @@
     "electron-builder": "^25.1.8",
     "eslint": "^9.11.1",
     "eslint-plugin-import": "^2.31.0",
+    "eslint-plugin-jsdoc": "^50.4.3",
     "eslint-plugin-jsonc": "^2.16.0",
     "eslint-plugin-unicorn": "^56.0.0",
     "eslint-plugin-vue": "^9.30.0",

src/renderer/components/ChannelDetails/ChannelDetails.vue

@@ -280,14 +280,17 @@ const props = defineProps({
 
 const emit = defineEmits(['change-tab', 'search', 'subscribed'])
 
+/** @type {import('vue').ComputedRef<boolean>} */
 const hideChannelSubscriptions = computed(() => {
   return store.getters.getHideChannelSubscriptions
 })
 
+/** @type {import('vue').ComputedRef<boolean>} */
 const hideSharingActions = computed(() => {
   return store.getters.getHideSharingActions
 })
 
+/** @type {import('vue').ComputedRef<boolean>} */
 const hideUnsubscribeButton = computed(() => {
   return store.getters.getHideUnsubscribeButton
 })

src/renderer/components/FtCommunityPost/FtCommunityPost.vue

@@ -198,10 +198,12 @@ const props = defineProps({
   },
 })
 
+/** @type {import('vue').ComputedRef<'grid' | 'list'>} */
 const listType = computed(() => {
   return store.getters.getListType
 })
 
+/** @type {import('vue').ComputedRef<string[]>} */
 const forbiddenTitles = computed(() => {
   if (!props.hideForbiddenTitles) { return [] }
   return JSON.parse(store.getters.getForbiddenTitles)
@@ -211,10 +213,12 @@ const hideVideo = computed(() => {
   return forbiddenTitles.value.some((text) => props.data.postContent.content.title?.toLowerCase().includes(text.toLowerCase()))
 })
 
+/** @type {import('vue').ComputedRef<'local' | 'invidious'>} */
 const backendPreference = computed(() => {
   return store.getters.getBackendPreference
 })
 
+/** @type {import('vue').ComputedRef<boolean>} */
 const backendFallback = computed(() => {
   return store.getters.getBackendFallback
 })
@@ -226,11 +230,13 @@ const isInvidiousAllowed = computed(() => {
 let postType = ''
 let postText = ''
 let postId = ''
+/** @type {string[]?} */
 let authorThumbnails = null
 let postContent = ''
 let author = ''
 let authorId = ''
 let voteCount = 0
+/** @type {number?} */
 let commentCount = null
 
 parseCommunityData()

src/renderer/components/FtElementList/FtElementList.vue

@@ -104,10 +104,12 @@ const props = defineProps({
 
 const emit = defineEmits(['move-video-down', 'move-video-up', 'remove-from-playlist'])
 
+/** @type {import('vue').ComputedRef<'grid' | 'list'>} */
 const listType = computed(() => {
   return store.getters.getListType
 })
 
+/** @type {import('vue').ComputedRef<'grid' | 'list'>} */
 const displayValue = computed(() => {
   return props.display === '' ? listType.value : props.display
 })

src/renderer/components/FtListChannel/FtListChannel.vue

@@ -91,23 +91,29 @@ const props = defineProps({
   }
 })
 
+/** @type {import('vue').ComputedRef<string>} */
 const currentInvidiousInstanceUrl = computed(() => {
   return store.getters.getCurrentInvidiousInstanceUrl
 })
 
+/** @type {import('vue').ComputedRef<'grid' | 'list'>} */
 const listType = computed(() => {
   return store.getters.getListType
 })
 
+/** @type {import('vue').ComputedRef<boolean>} */
 const hideChannelSubscriptions = computed(() => {
   return store.getters.getHideChannelSubscriptions
 })
 
 let id = ''
 let thumbnail = ''
 let name = ''
+/** @type {number?} */
 let subscriberCount = null
+/** @type {number?} */
 let videoCount = null
+/** @type {string?} */
 let handle = null
 let description = ''
 
@@ -155,6 +161,7 @@ function parseLocalData() {
 
 function parseInvidiousData() {
   // Can be prefixed with `https://` or `//` (protocol relative)
+  /** @type {string} */
   const thumbnailUrl = props.data.authorThumbnails[2].url
 
   thumbnail = youtubeImageUrlToInvidious(thumbnailUrl, currentInvidiousInstanceUrl.value)

src/renderer/components/FtListHashtag/FtListHashtag.vue

@@ -67,13 +67,18 @@ const props = defineProps({
   }
 })
 
+/** @type {import('vue').ComputedRef<'list'| 'grid'>} */
 const listType = computed(() => {
   return store.getters.getListType
 })
 
+/** @type {string} */
 const title = props.data.title
+/** @type {number} */
 const channelCount = props.data.channelCount
+/** @type {number} */
 const videoCount = props.data.videoCount
+/** @type {string} */
 const url = `/hashtag/${encodeURIComponent(title.substring(1))}`
 
 const formattedChannelCount = computed(() => {

src/renderer/components/FtListLazyWrapper/FtListLazyWrapper.vue

@@ -141,18 +141,22 @@ const props = defineProps({
 
 const emit = defineEmits(['move-video-down', 'move-video-up', 'remove-from-playlist'])
 
+/** @type {import('vue').ComputedRef<'video' | 'shortVideo' | 'channel' | 'playlist' | 'community'>} */
 const finalDataType = computed(() => {
   return props.data.type ?? props.dataType
 })
 
+/** @type {import('vue').ComputedRef<boolean>} */
 const hideLiveStreams = computed(() => {
   return store.getters.getHideLiveStreams
 })
 
+/** @type {import('vue').ComputedRef<boolean>} */
 const hideUpcomingPremieres = computed(() => {
   return store.getters.getHideUpcomingPremieres
 })
 
+/** @type {import('vue').ComputedRef<{name : string, preferredName: string, icon: string}[]>} */
 const channelsHidden = computed(() => {
   // Some component users like channel view will have this disabled
   if (!props.useChannelsHiddenPreference) { return [] }
@@ -166,6 +170,7 @@ const channelsHidden = computed(() => {
   })
 })
 
+/** @type {string[]} */
 const forbiddenTitles = computed(() => {
   if (!props.hideForbiddenTitles) { return [] }
   return JSON.parse(store.getters.getForbiddenTitles)

src/renderer/components/WatchVideoChapters/WatchVideoChapters.vue

@@ -106,10 +106,12 @@ const currentChapter = computed(() => {
   return props.chapters[currentIndex.value]
 })
 
+/** @type {import('vue').ComputedRef<string>} */
 const currentTitle = computed(() => {
   return currentChapter.value.title
 })
 
+/** @type {import('vue').ComputedRef<boolean>} */
 const compact = computed(() => {
   return !props.chapters[0].thumbnail
 })

src/renderer/components/WatchVideoDescription/WatchVideoDescription.vue

@@ -60,6 +60,7 @@ function onTimestamp(timestamp) {
 
 /**
  * @param {string} descriptionText
+ * @returns {string}
  */
 function parseDescriptionHtml(descriptionText) {
   return descriptionText

src/renderer/components/WatchVideoRecommendations/WatchVideoRecommendations.vue

@@ -46,6 +46,7 @@ defineProps({
   }
 })
 
+/** @type {import('vue').ComputedRef<boolean>} */
 const playNextVideo = computed(() => {
   return store.getters.getPlayNextVideo
 })

src/renderer/components/ft-shaka-video-player/ft-shaka-video-player.js

@@ -355,7 +355,7 @@ export default defineComponent({
        *     color: string,
        *     skip: 'autoSkip' | 'promptToSkip' | 'showInSeekBar' | 'doNothing'
        *   }
-       * }} */
+        }} */
       const categoryData = {}
 
       sponsorCategories.forEach(x => {
@@ -537,7 +537,7 @@ export default defineComponent({
      * @param {'dash'|'audio'|'legacy'} format
      * @param {boolean} useAutoQuality
      * @returns {shaka.extern.PlayerConfiguration}
-     **/
+     */
     function getPlayerConfig(format, useAutoQuality = false) {
       return {
         // YouTube uses these values and they seem to work well in FreeTube too,
@@ -1870,7 +1870,7 @@ export default defineComponent({
 
     /**
      * @param {WheelEvent} event
-     * */
+     */
     function mouseScrollVolume(event) {
       if (!event.ctrlKey && !event.metaKey) {
         event.preventDefault()
@@ -2145,7 +2145,7 @@ export default defineComponent({
     /**
      * @param {shaka.util.Error} error
      * @param {string} context
-     * @param {object=} details
+     * @param {object?} details
      */
     function handleError(error, context, details) {
       logShakaError(error, context, props.videoId, details)

src/renderer/components/ft-shaka-video-player/player-components/AudioTrackSelection.js

@@ -42,7 +42,7 @@ export class AudioTrackSelection extends shaka.ui.SettingsMenu {
 
   /**
    * @private
-   * @param {shaka.extern.TrackList=} tracks
+   * @param {shaka.extern.TrackList?} tracks
    */
   updateAudioTracks_(tracks) {
     if (!tracks) {

src/renderer/components/ft-share-button/ft-share-button.js

@@ -19,7 +19,7 @@ export default defineComponent({
        * Allows to render the dropdown conditionally
        * 'Channel' will exclude embed links
        * 'Video' (default) keeps the original behaviour
-       **/
+       */
       type: String,
       default: 'Video'
     },

src/renderer/helpers/accessibility.js

@@ -1,3 +1,7 @@
+/**
+ * @param {string} attribute
+ * @returns {string}
+ */
 export function sanitizeForHtmlId(attribute) {
   return attribute.replaceAll(/\s+/g, '')
 }

src/renderer/helpers/api/invidious.js

@@ -142,6 +142,11 @@ export async function invidiousGetCommentReplies({ id, replyToken }) {
   return { commentData: parseInvidiousCommentData(response), continuation: response.continuation ?? null }
 }
 
+/**
+ * @param {string} url
+ * @param {string?} currentInstance
+ * @returns {string}
+ */
 export function youtubeImageUrlToInvidious(url, currentInstance = null) {
   if (url == null) {
     return null

src/renderer/helpers/api/local.js

@@ -550,15 +550,15 @@ export async function getLocalArtistTopicChannelReleasesContinuation(channel, co
  * @param {boolean} onlyIdNameThumbnail
  */
 export function parseLocalChannelHeader(channel, onlyIdNameThumbnail = false) {
-  /** @type {string=} */
+  /** @type {string?} */
   let id
   /** @type {string} */
   let name
-  /** @type {string=} */
+  /** @type {string?} */
   let thumbnailUrl
-  /** @type {string=} */
+  /** @type {string?} */
   let bannerUrl
-  /** @type {string=} */
+  /** @type {string?} */
   let subscriberText
   /** @type {string[]} */
   const tags = []
@@ -766,7 +766,7 @@ export function parseLocalChannelShorts(shorts, channelId, channelName) {
 /**
  * @param {import('youtubei.js').YTNodes.Playlist|import('youtubei.js').YTNodes.GridPlaylist|import('youtubei.js').YTNodes.LockupView} playlist
  * @param {string} channelId
- * @param {string} chanelName
+ * @param {string} channelName
  */
 export function parseLocalListPlaylist(playlist, channelId = undefined, channelName = undefined) {
   if (playlist.type === 'LockupView') {

src/renderer/helpers/channels.js

@@ -4,11 +4,11 @@ import { getLocalChannel, parseLocalChannelHeader } from './api/local'
 /**
  * @param {string} id
  * @param {{
-*   preference: string,
-*   fallback: boolean,
-*   invalid: boolean,
-* }} backendOptions
-*/
+ *   preference: string,
+ *   fallback: boolean,
+ *   invalid: boolean,
+ * }} backendOptions
+ */
 async function findChannelById(id, backendOptions) {
   try {
     if (!process.env.SUPPORTS_LOCAL_API || backendOptions.preference === 'invidious') {
@@ -37,11 +37,11 @@ async function findChannelById(id, backendOptions) {
 /**
  * @param {string} id
  * @param {{
-*   preference: string,
-*   fallback: boolean,
-* }} backendOptions
-* @returns {Promise<{icon: string, iconHref: string, preferredName: string} | { invalidId: boolean }>}
-*/
+ *   preference: string,
+ *   fallback: boolean,
+ * }} backendOptions
+ * @returns {Promise<{icon: string, iconHref: string, preferredName: string} | { invalidId: boolean }>}
+ */
 export async function findChannelTagInfo(id, backendOptions) {
   if (!checkYoutubeChannelId(id)) return { invalidId: true }
   try {