Update jsdocs for search podcasts

server/controllers/SearchController.js

@@ -43,14 +43,14 @@ class SearchController {
    */
   async findPodcasts(req, res) {
     const term = req.query.term
-    const country = req.query.country
+    const country = req.query.country || 'us'
     if (!term) {
       Logger.error('[SearchController] Invalid request query param "term" is required')
       return res.status(400).send('Invalid request query param "term" is required')
     }
 
     const results = await PodcastFinder.search(term, {
-      country: country
+      country
     })
     res.json(results)
   }

server/finders/PodcastFinder.js

@@ -6,10 +6,16 @@ class PodcastFinder {
     this.iTunesApi = new iTunes()
   }
 
+  /**
+   * 
+   * @param {string} term 
+   * @param {{country:string}} options 
+   * @returns {Promise<import('../providers/iTunes').iTunesPodcastSearchResult[]>}
+   */
   async search(term, options = {}) {
     if (!term) return null
     Logger.debug(`[iTunes] Searching for podcast with term "${term}"`)
-    var results = await this.iTunesApi.searchPodcasts(term, options)
+    const results = await this.iTunesApi.searchPodcasts(term, options)
     Logger.debug(`[iTunes] Podcast search for "${term}" returned ${results.length} results`)
     return results
   }

server/providers/iTunes.js

@@ -2,16 +2,46 @@ const axios = require('axios')
 const Logger = require('../Logger')
 const htmlSanitizer = require('../utils/htmlSanitizer')
 
+/**
+ * @typedef iTunesSearchParams
+ * @property {string} term
+ * @property {string} country
+ * @property {string} media
+ * @property {string} entity
+ * @property {number} limit
+ */
+
+/**
+ * @typedef iTunesPodcastSearchResult
+ * @property {string} id
+ * @property {string} artistId
+ * @property {string} title
+ * @property {string} artistName
+ * @property {string} description
+ * @property {string} descriptionPlain
+ * @property {string} releaseDate
+ * @property {string[]} genres
+ * @property {string} cover
+ * @property {string} feedUrl
+ * @property {string} pageUrl
+ * @property {boolean} explicit
+ */
+
 class iTunes {
   constructor() { }
 
-  // https://developer.apple.com/library/archive/documentation/AudioVideo/Conceptual/iTuneSearchAPI/Searching.html
+  /**
+   * @see https://developer.apple.com/library/archive/documentation/AudioVideo/Conceptual/iTuneSearchAPI/Searching.html
+   * 
+   * @param {iTunesSearchParams} options 
+   * @returns {Promise<Object[]>}
+   */
   search(options) {
     if (!options.term) {
       Logger.error('[iTunes] Invalid search options - no term')
       return []
     }
-    var query = {
+    const query = {
       term: options.term,
       media: options.media,
       entity: options.entity,
@@ -82,6 +112,11 @@ class iTunes {
     })
   }
 
+  /**
+   * 
+   * @param {Object} data 
+   * @returns {iTunesPodcastSearchResult}
+   */
   cleanPodcast(data) {
     return {
       id: data.collectionId,
@@ -100,6 +135,12 @@ class iTunes {
     }
   }
 
+  /**
+   * 
+   * @param {string} term 
+   * @param {{country:string}} options 
+   * @returns {Promise<iTunesPodcastSearchResult[]>}
+   */
   searchPodcasts(term, options = {}) {
     return this.search({ term, entity: 'podcast', media: 'podcast', ...options }).then((results) => {
       return results.map(this.cleanPodcast.bind(this))