Various places: jsdoc fixes

libraries/ortbConverter/lib/composer.js

@@ -11,13 +11,13 @@ const SORTED = new WeakMap();
 
 /**
  *
- * @param {Object[string, Component]} components to compose
- * @param {Object[string, function|boolean]} overrides a map from component name, to a function that should override that component.
+ * @param {Object.<string, Component>} components - An object where keys are component names and values are components to compose.
+ * @param {Object.<string, (function|boolean)>} overrides - A map from component names to functions that should override those components.
  * Override functions are replacements, except that they get the original function they are overriding as their first argument. If the override
  * is `false`, the component is disabled.
  *
- * @return a function that will run all components in order of priority, with functions from `overrides` taking
- * precedence over components that match names
+ * @return {function} - A function that will run all components in order of priority, with functions from `overrides` taking
+ * precedence over components that match names.
  */
 export function compose(components, overrides = {}) {
   if (!SORTED.has(components)) {

libraries/video/constants/ortb.js

@@ -1,6 +1,6 @@
 /**
  * @typedef {Object} OrtbParams
- * @property {OrtbVideoParamst} video
+ * @property {OrtbVideoParams} video
  * @property {OrtbContentParams} content
  */
 

modules/paapi.js

@@ -272,11 +272,11 @@ function expandFilters({auctionId, adUnitCode} = {}) {
 /**
  * Get PAAPI auction configuration.
  *
- * @param filters
- * @param filters.auctionId? optional auction filter; if omitted, the latest auction for each ad unit is used
- * @param filters.adUnitCode? optional ad unit filter
- * @param includeBlanks if true, include null entries for ad units that match the given filters but do not have any available auction configs.
- * @returns {{}} a map from ad unit code to auction config for the ad unit.
+ * @param {Object} [filters] - Filters object
+ * @param {string} [filters.auctionId] optional auction filter; if omitted, the latest auction for each ad unit is used
+ * @param {string} [filters.adUnitCode] optional ad unit filter
+ * @param {boolean} [includeBlanks=false] if true, include null entries for ad units that match the given filters but do not have any available auction configs.
+ * @returns {Object} a map from ad unit code to auction config for the ad unit.
  */
 export function getPAAPIConfig(filters = {}, includeBlanks = false) {
   const output = {};

modules/videoModule/coreVideo.js

@@ -104,7 +104,6 @@ import { ParentModule, SubmoduleBuilder } from '../../libraries/video/shared/par
 
 /**
  * @summary Maps a Video Provider factory to the video player's vendor code.
- * @type {vendorSubmoduleDirectory}
  */
 const videoVendorDirectory = {};
 

modules/videoModule/gamAdServerSubmodule.js

@@ -4,7 +4,6 @@ import { getGlobal } from '../../src/prebidGlobal.js';
 /**
  * @constructor
  * @param {Object} dfpModule_ - the DFP ad server module
- * @returns {AdServerProvider}
  */
 function GamAdServerProvider(dfpModule_) {
   const dfp = dfpModule_;

src/activities/params.js

@@ -40,8 +40,10 @@ export const ACTIVITY_PARAM_SYNC_TYPE = 'syncType'
 export const ACTIVITY_PARAM_SYNC_URL = 'syncUrl';
 /**
  * @private
- * configuration options for analytics adapter - the argument passed to `enableAnalytics`.
- * relevant for: reportAnalytics
+ * Configuration options for analytics adapter - the argument passed to `enableAnalytics`.
+ * Relevant for: reportAnalytics.
+ * @constant
+ * @type {string}
  */
 export const ACTIVITY_PARAM_ANL_CONFIG = '_config';
 

src/activities/rules.js

@@ -40,19 +40,19 @@ export function ruleRegistry(logger = prefixLog('Activity control:')) {
     /**
      * Register an activity control rule.
      *
-     * @param {string} activity activity name - set is defined in `activities.js`
-     * @param {string} ruleName a name for this rule; used for logging.
-     * @param {function({}): {allow: boolean, reason?: string}} rule definition function. Takes in activity
+     * @param {string} activity - Activity name, as defined in `activities.js`.
+     * @param {string} ruleName - A name for this rule, used for logging.
+     * @param {function(Object): {allow: boolean, reason?: string}} rule - Rule definition function. Takes in activity
      *        parameters as a single map; MAY return an object {allow, reason}, where allow is true/false,
      *        and reason is an optional message used for logging.
      *
-     *        {allow: true} will allow this activity AS LONG AS no other rules with same or higher priority return {allow: false};
+     *        {allow: true} will allow this activity AS LONG AS no other rules with the same or higher priority return {allow: false};
      *        {allow: false} will deny this activity AS LONG AS no other rules with higher priority return {allow: true};
-     *        returning null/undefined has no effect - the decision is left to other rules.
+     *        Returning null/undefined has no effect - the decision is left to other rules.
      *        If no rule returns an allow value, the default is to allow the activity.
      *
-     * @param {number} priority rule priority; lower number means higher priority
-     * @returns {function(void): void} a function that unregisters the rule when called.
+     * @param {number} [priority=10] - Rule priority; lower number means higher priority.
+     * @returns {function(): void} - A function that unregisters the rule when called.
      */
     function registerActivityControl(activity, ruleName, rule, priority = 10) {
       const rules = getRules(activity);

src/adapterManager.js

@@ -230,9 +230,11 @@ export function getS2SBidderSet(s2sConfigs) {
 }
 
 /**
- * @returns {{[PARTITIONS.CLIENT]: Array<String>, [PARTITIONS.SERVER]: Array<String>}}
- *           All the bidder codes in the given `adUnits`, divided in two arrays -
- *           those that should be routed to client, and server adapters (according to the configuration in `s2sConfigs`).
+ * @param {Array} adUnits - The ad units to be processed.
+ * @param {Object} s2sConfigs - The server-to-server configurations.
+ * @returns {Object} - An object containing arrays of bidder codes for client and server.
+ * @returns {Object} return.client - Array of bidder codes that should be routed to client adapters.
+ * @returns {Object} return.server - Array of bidder codes that should be routed to server adapters.
  */
 export function _partitionBidders (adUnits, s2sConfigs, {getS2SBidders = getS2SBidderSet} = {}) {
   const serverBidders = getS2SBidders(s2sConfigs);

src/consentHandler.js

@@ -163,14 +163,19 @@ export function gvlidRegistry() {
         }
       }
     },
+    /**
+     * @typedef {Object} GvlIdResult
+     * @property {Object.<string, number>} modules - A map from module type to that module's GVL ID.
+     * @property {number} [gvlid] - The single GVL ID for this family of modules (only defined if all modules with this name declared the same ID).
+     */
+
     /**
      * Get a module's GVL ID(s).
      *
-     * @param {string} moduleName
-     * @return {{modules: {[moduleType]: number}, gvlid?: number}} an object where:
+     * @param {string} moduleName - The name of the module.
+     * @return {GvlIdResult} An object where:
      *   `modules` is a map from module type to that module's GVL ID;
-     *   `gvlid` is the single GVL ID for this family of modules (only defined
-     *   if all modules with this name declared the same ID).
+     *   `gvlid` is the single GVL ID for this family of modules (only defined if all modules with this name declare the same ID).
      */
     get(moduleName) {
       const result = {modules: registry[moduleName] || {}};

src/fpd/enrichment.js

@@ -23,9 +23,9 @@ export const dep = {
 const oneClient = clientSectionChecker('FPD')
 
 /**
- * Enrich an ortb2 object with first party data.
- * @param {Promise[{}]} fpd: a promise to an ortb2 object.
- * @returns: {Promise[{}]}: a promise to an enriched ortb2 object.
+ * Enrich an ortb2 object with first-party data.
+ * @param {Promise<Object>} fpd - A promise that resolves to an ortb2 object.
+ * @returns {Promise<Object>} - A promise that resolves to an enriched ortb2 object.
  */
 export const enrichFPD = hook('sync', (fpd) => {
   const promArr = [fpd, getSUA().catch(() => null), tryToGetCdepLabel().catch(() => null)];

src/prebid.js

@@ -283,7 +283,7 @@ pbjsInstance.getAdserverTargetingForAdUnitCodeStr = function (adunitCode) {
 
 /**
  * This function returns the query string targeting parameters available at this moment for a given ad unit. Note that some bidder's response may not have been received if you call this function too quickly after the requests are sent.
- * @param adUnitCode {string} adUnitCode to get the bid responses for
+ * @param adunitCode {string} adUnitCode to get the bid responses for
  * @alias module:pbjs.getHighestUnusedBidResponseForAdUnitCode
  * @returns {Object}  returnObj return bid
  */
@@ -393,7 +393,7 @@ pbjsInstance.getBidResponsesForAdUnitCode = function (adUnitCode) {
 /**
  * Set query string targeting on one or more GPT ad units.
  * @param {(string|string[])} adUnit a single `adUnit.code` or multiple.
- * @param {function(object)} customSlotMatching gets a GoogleTag slot and returns a filter function for adUnitCode, so you can decide to match on either eg. return slot => { return adUnitCode => { return slot.getSlotElementId() === 'myFavoriteDivId'; } };
+ * @param {function(object): function(string): boolean} customSlotMatching gets a GoogleTag slot and returns a filter function for adUnitCode, so you can decide to match on either eg. return slot => { return adUnitCode => { return slot.getSlotElementId() === 'myFavoriteDivId'; } };
  * @alias module:pbjs.setTargetingForGPTAsync
  */
 pbjsInstance.setTargetingForGPTAsync = function (adUnit, customSlotMatching) {
@@ -426,7 +426,7 @@ pbjsInstance.setTargetingForGPTAsync = function (adUnit, customSlotMatching) {
 
 /**
  * Set query string targeting on all AST (AppNexus Seller Tag) ad units. Note that this function has to be called after all ad units on page are defined. For working example code, see [Using Prebid.js with AppNexus Publisher Ad Server](http://prebid.org/dev-docs/examples/use-prebid-with-appnexus-ad-server.html).
- * @param  {(string|string[])} adUnitCode adUnitCode or array of adUnitCodes
+ * @param  {(string|string[])} adUnitCodes adUnitCode or array of adUnitCodes
  * @alias module:pbjs.setTargetingForAst
  */
 pbjsInstance.setTargetingForAst = function (adUnitCodes) {

src/refererDetection.js

@@ -34,9 +34,11 @@ export function ensureProtocol(url, win = window) {
 
 /**
  * Extract the domain portion from a URL.
- * @param url
- * @param noLeadingWww: if true, remove 'www.' appearing at the beginning of the domain.
- * @param noPort: if true, do not include the ':[port]' portion
+ * @param {string} url - The URL to extract the domain from.
+ * @param {Object} options - Options for parsing the domain.
+ * @param {boolean} options.noLeadingWww - If true, remove 'www.' appearing at the beginning of the domain.
+ * @param {boolean} options.noPort - If true, do not include the ':[port]' portion.
+ * @return {string|undefined} - The extracted domain or undefined if the URL is invalid.
  */
 export function parseDomain(url, {noLeadingWww = false, noPort = false} = {}) {
   try {
@@ -108,13 +110,13 @@ export function detectReferer(win) {
    * @property {string|null} ref the referrer (document.referrer) to the current page, or null if not available (due to cross-origin restrictions)
    * @property {string} topmostLocation of the top-most frame for which we could guess the location. Outside of cross-origin scenarios, this is equivalent to `location`.
    * @property {number} numIframes number of steps between window.self and window.top
-   * @property {Array[string|null]} stack our best guess at the location for each frame, in the direction top -> self.
+   * @property {Array<string|null>} stack our best guess at the location for each frame, in the direction top -> self.
    */
 
   /**
    * Walk up the windows to get the origin stack and best available referrer, canonical URL, etc.
    *
-   * @returns {refererInfo}
+   * @returns {refererInfo} An object containing referer information.
    */
   function refererInfo() {
     const stack = [];

src/targeting.js

@@ -482,7 +482,8 @@ export function newTargeting(auctionManager) {
   /**
    * Returns top bids for a given adUnit or set of adUnits.
    * @param  {(string|string[])} adUnitCode adUnitCode or array of adUnitCodes
-   * @return {[type]}            [description]
+   * @param  {Array} [bidsReceived=getBidsReceived()] - The received bids, defaulting to the result of getBidsReceived().
+   * @return {Array<Object>} - An array of winning bids.
    */
   targeting.getWinningBids = function(adUnitCode, bidsReceived = getBidsReceived()) {
     const adUnitCodes = getAdUnitCodes(adUnitCode);

src/utils/ttlCollection.js

@@ -4,19 +4,26 @@ import {binarySearch, logError, timestamp} from '../utils.js';
 /**
  * Create a set-like collection that automatically forgets items after a certain time.
  *
- * @param {({}) => Number|Promise<Number>} startTime? a function taking an item added to this collection,
+ * @param {function(*): (number|Promise<number>)} [startTime=timestamp] - A function taking an item added to this collection,
  *   and returning (a promise to) a timestamp to be used as the starting time for the item
  *   (the item will be dropped after `ttl(item)` milliseconds have elapsed since this timestamp).
  *   Defaults to the time the item was added to the collection.
- * @param {({}) => Number|void|Promise<Number|void>} ttl a function taking an item added to this collection,
+ * @param {function(*): (number|void|Promise<number|void>)} [ttl=() => null] - A function taking an item added to this collection,
  *   and returning (a promise to) the duration (in milliseconds) the item should be kept in it.
  *   May return null to indicate that the item should be persisted indefinitely.
- * @param {boolean} monotonic? set to true for better performance, but only if, given any two items A and B in this collection:
+ * @param {boolean} [monotonic=false] - Set to true for better performance, but only if, given any two items A and B in this collection:
  *   if A was added before B, then:
  *     - startTime(A) + ttl(A) <= startTime(B) + ttl(B)
  *     - Promise.all([startTime(A), ttl(A)]) never resolves later than Promise.all([startTime(B), ttl(B)])
- * @param {number} slack? maximum duration (in milliseconds) that an item is allowed to persist
+ * @param {number} [slack=5000] - Maximum duration (in milliseconds) that an item is allowed to persist
  *   once past its TTL. This is also roughly the interval between "garbage collection" sweeps.
+ * @returns {Object} A set-like collection with automatic TTL expiration.
+ * @returns {function(*)} return.add - Add an item to the collection.
+ * @returns {function()} return.clear - Clear the collection.
+ * @returns {function(): Array<*>} return.toArray - Get all the items in the collection, in insertion order.
+ * @returns {function()} return.refresh - Refresh the TTL for each item in the collection.
+ * @returns {function(function(*))} return.onExpiry - Register a callback to be run when an item has expired and is about to be
+ *   removed from the collection.
  */
 export function ttlCollection(
   {

src/video.js

@@ -25,7 +25,8 @@ export function fillVideoDefaults(adUnit) {
 /**
  * Validate that the assets required for video context are present on the bid
  * @param {VideoBid} bid Video bid to validate
- * @param index
+ * @param {Object} [options] - Options object
+ * @param {Object} [options.index=auctionManager.index] - Index object, defaulting to `auctionManager.index`
  * @return {Boolean} If object is valid
  */
 export function isValidVideoBid(bid, {index = auctionManager.index} = {}) {

src/videoCache.js

@@ -39,7 +39,7 @@ const ttlBufferInSeconds = 15;
  * Function which wraps a URI that serves VAST XML, so that it can be loaded.
  *
  * @param {string} uri The URI where the VAST content can be found.
- * @param {string} impUrl An impression tracker URL for the delivery of the video ad
+ * @param {(string|string[])} impTrackerURLs An impression tracker URL for the delivery of the video ad
  * @return A VAST URL which loads XML from the given URI.
  */
 function wrapURI(uri, impTrackerURLs) {
@@ -65,7 +65,9 @@ function wrapURI(uri, impTrackerURLs) {
  * the bid can't be converted cleanly.
  *
  * @param {CacheableBid} bid
- * @param index
+ * @param {Object} [options] - Options object.
+ * @param {Object} [options.index=auctionManager.index] - Index object, defaulting to `auctionManager.index`.
+ * @return {Object|null} - The payload to be sent to the prebid-server endpoints, or null if the bid can't be converted cleanly.
  */
 function toStorageRequest(bid, {index = auctionManager.index} = {}) {
   const vastValue = bid.vastXml ? bid.vastXml : wrapURI(bid.vastUrl, bid.vastImpUrl);