Core Utils: fix jsdoc warnings (prebid#11694)

* Update utils.js

* Update perfMetrics.js

* Update ttlCollection.js

* Update adpod.js

* Update consentManagementGpp.js

* Update consentManagementGpp.js

* Update consentManagement.js

* Update consentManagementUsp.js

* Update currency.js

* Update dfpAdServerVideo.js

* Update instreamTracking.js

* Update s2sTesting.js

* Update sizeMapping.js

* Update topicsFpdModule.js

* Update uid2IdSystem.js

* Update consentManagementUsp.js

* Update sizeMapping.js

Author: patmmccann

modules/adpod.js

@@ -451,7 +451,6 @@ export function callPrebidCacheAfterAuction(bids, callback) {
 /**
  * Compare function to be used in sorting long-form bids. This will compare bids on price per second.
  * @param {Object} bid
- * @param {Object} bid
  */
 export function sortByPricePerSecond(a, b) {
   if (a.adserverTargeting[TARGETING_KEYS.PRICE_BUCKET] / a.video.durationBucket < b.adserverTargeting[TARGETING_KEYS.PRICE_BUCKET] / b.video.durationBucket) {
@@ -465,10 +464,10 @@ export function sortByPricePerSecond(a, b) {
 
 /**
  * This function returns targeting keyvalue pairs for long-form adserver modules. Freewheel and GAM are currently supporting Prebid long-form
- * @param {Object} options
- * @param {Array[string]} codes
- * @param {function} callback
- * @returns targeting kvs for adUnitCodes
+ * @param {Object} options - Options for targeting.
+ * @param {Array<string>} options.codes - Array of ad unit codes.
+ * @param {function} options.callback - Callback function to handle the targeting key-value pairs.
+ * @returns {Object} Targeting key-value pairs for ad unit codes.
  */
 export function getTargeting({ codes, callback } = {}) {
   if (!callback) {

modules/consentManagement.js

@@ -35,7 +35,9 @@ const cmpCallMap = {
 
 /**
  * This function reads the consent string from the config to obtain the consent information of the user.
- * @param {function({})} onSuccess acts as a success callback when the value is read from config; pass along consentObject from CMP
+ * @param {Object} options - An object containing the callbacks.
+ * @param {function(Object): void} options.onSuccess - Acts as a success callback when the value is read from config; pass along consentObject from CMP.
+ * @param {function(string, ...Object?): void} [options.onError] - Acts as an error callback while interacting with CMP; pass along an error message (string) and any extra error arguments (purely for logging). Optional.
  */
 function lookupStaticConsentData({onSuccess, onError}) {
   processCmpData(staticConsentData, {onSuccess, onError})
@@ -45,8 +47,10 @@ function lookupStaticConsentData({onSuccess, onError}) {
  * This function handles interacting with an IAB compliant CMP to obtain the consent information of the user.
  * Given the async nature of the CMP's API, we pass in acting success/error callback functions to exit this function
  * based on the appropriate result.
- * @param {function({})} onSuccess acts as a success callback when CMP returns a value; pass along consentObjectfrom CMP
- * @param {function(string, ...{}?)} cmpError acts as an error callback while interacting with CMP; pass along an error message (string) and any extra error arguments (purely for logging)
+ * @param {Object} options - An object containing the callbacks.
+ * @param {function(Object): void} options.onSuccess - Acts as a success callback when CMP returns a value; pass along consentObject from CMP.
+ * @param {function(string, ...Object?): void} options.onError - Acts as an error callback while interacting with CMP; pass along an error message (string) and any extra error arguments (purely for logging).
+ * @param {function(Object): void} options.onEvent - Acts as an event callback for processing TCF data events from CMP.
  */
 function lookupIabConsent({onSuccess, onError, onEvent}) {
   function cmpResponseCallback(tcfData, success) {

modules/consentManagementGpp.js

@@ -304,8 +304,10 @@ class GPP11Client extends GPPClient {
  * This function handles interacting with an IAB compliant CMP to obtain the consent information of the user.
  * Given the async nature of the CMP's API, we pass in acting success/error callback functions to exit this function
  * based on the appropriate result.
- * @param {function({})} onSuccess acts as a success callback when CMP returns a value; pass along consentObjectfrom CMP
- * @param {function(string, ...{}?)} cmpError acts as an error callback while interacting with CMP; pass along an error message (string) and any extra error arguments (purely for logging)
+ * @param {Object} options - An object containing the callbacks.
+ * @param {function(Object): void} options.onSuccess - Acts as a success callback when CMP returns a value; pass along consentObject from CMP.
+ * @param {function(string, ...Object?): void} options.onError - Acts as an error callback while interacting with CMP; pass along an error message (string) and any extra error arguments (purely for logging).
+ * @param {function(): Object} [mkCmp=cmpClient] - A function to create the CMP client. Defaults to `cmpClient`.
  */
 export function lookupIabConsent({onSuccess, onError}, mkCmp = cmpClient) {
   pipeCallbacks(() => GPPClient.init(mkCmp).then(([client, gppDataPm]) => gppDataPm), {onSuccess, onError});
@@ -434,7 +436,6 @@ function processCmpData(consentData) {
 /**
  * Stores CMP data locally in module to make information available in adaptermanager.js for later in the auction
  * @param {{}} gppData the result of calling a CMP's `getGPPData` (or equivalent)
- * @param {{}} sectionData map from GPP section name to the result of calling a CMP's `getSection` (or equivalent)
  */
 export function storeConsentData(gppData = {}) {
   consentData = {

modules/consentManagementUsp.js

@@ -163,10 +163,12 @@ export const requestBidsHook = timedAuctionHook('usp', function requestBidsHook(
 /**
  * This function checks the consent data provided by USPAPI to ensure it's in an expected state.
  * If it's bad, we exit the module depending on config settings.
- * If it's good, then we store the value and exits the module.
- * @param {object} consentObject required; object returned by USPAPI that contains user's consent choices
- * @param {function(string)} onSuccess callback accepting the resolved consent USP consent string
- * @param {function(string, ...{}?)} onError callback accepting error message and any extra error arguments (used purely for logging)
+ * If it's good, then we store the value and exit the module.
+ *
+ * @param {Object} consentObject - The object returned by USPAPI that contains the user's consent choices.
+ * @param {Object} callbacks - An object containing the callback functions.
+ * @param {function(string): void} callbacks.onSuccess - Callback accepting the resolved USP consent string.
+ * @param {function(string, ...Object?): void} callbacks.onError - Callback accepting an error message and any extra error arguments (used purely for logging).
  */
 function processUspData(consentObject, {onSuccess, onError}) {
   const valid = !!(consentObject && consentObject.usPrivacy);

modules/currency.js

@@ -28,6 +28,7 @@ export let responseReady = defer();
 
 /**
  * Configuration function for currency
+ * @param {object} config
  * @param  {string} [config.adServerCurrency = 'USD']
  *  ISO 4217 3-letter currency code that represents the target currency. (e.g. 'EUR').  If this value is present,
  *  the currency conversion feature is activated.

modules/dfpAdServerVideo.js

@@ -308,7 +308,7 @@ export function buildAdpodVideoUrl({code, params, callback} = {}) {
  * Builds a video url from a base dfp video url and a winning bid, appending
  * Prebid-specific key-values.
  * @param {Object} components base video adserver url parsed into components object
- * @param {AdapterBidResponse} bid winning bid object to append parameters from
+ * @param {Object} bid winning bid object to append parameters from
  * @param {Object} options Options which should be used to construct the URL (used for custom params).
  * @return {string} video url
  */
@@ -325,7 +325,7 @@ function buildUrlFromAdserverUrlComponents(components, bid, options) {
 /**
  * Returns the encoded vast url if it exists on a bid object, only if prebid-cache
  * is disabled, and description_url is not already set on a given input
- * @param {AdapterBidResponse} bid object to check for vast url
+ * @param {Object} bid object to check for vast url
  * @param {Object} components the object to check that description_url is NOT set on
  * @param {string} prop the property of components that would contain description_url
  * @return {string | undefined} The encoded vast url if it exists, or undefined
@@ -336,7 +336,7 @@ function getDescriptionUrl(bid, components, prop) {
 
 /**
  * Returns the encoded `cust_params` from the bid.adserverTargeting and adds the `hb_uuid`, and `hb_cache_id`. Optionally the options.params.cust_params
- * @param {AdapterBidResponse} bid
+ * @param {Object} bid
  * @param {Object} options this is the options passed in from the `buildDfpVideoUrl` function
  * @return {Object} Encoded key value pairs for cust_params
  */

modules/instreamTracking.js

@@ -41,9 +41,10 @@ const whitelistedResources = /video|fetch|xmlhttprequest|other/;
  *
  * Note: this is a workaround till a better approach is engineered.
  *
- * @param {Array<AdUnit>} adUnits
- * @param {Array<Bid>} bidsReceived
- * @param {Array<BidRequest>} bidderRequests
+ * @param {object} config
+ * @param {Array<AdUnit>} config.adUnits
+ * @param {Array<Bid>} config.bidsReceived
+ * @param {Array<BidRequest>} config.bidderRequests
  *
  * @return {boolean} returns TRUE if tracking started
  */

modules/s2sTesting.js

@@ -44,7 +44,7 @@ s2sTesting.getSourceBidderMap = function(adUnits = [], allS2SBidders = []) {
 
 /**
  * @function calculateBidSources determines the source for each s2s bidder based on bidderControl weightings.  these can be overridden at the adUnit level
- * @param s2sConfigs server-to-server configuration
+ * @param s2sConfig server-to-server configuration
  */
 s2sTesting.calculateBidSources = function(s2sConfig = {}) {
   // calculate bid source (server/client) for each s2s bidder

modules/sizeMapping.js

@@ -35,7 +35,7 @@ config.getConfig('sizeConfig', config => setSizeConfig(config.sizeConfig));
  * Returns object describing the status of labels on the adUnit or bidder along with labels passed into requestBids
  * @param bidOrAdUnit the bidder or adUnit to get label info on
  * @param activeLabels the labels passed to requestBids
- * @returns {LabelDescriptor}
+ * @returns {object}
  */
 export function getLabels(bidOrAdUnit, activeLabels) {
   if (bidOrAdUnit.labelAll) {
@@ -66,14 +66,18 @@ if (FEATURES.VIDEO) {
 }
 
 /**
- * Resolves the unique set of the union of all sizes and labels that are active from a SizeConfig.mediaQuery match
- * @param {Array<string>} labels Labels specified on adUnit or bidder
- * @param {boolean} labelAll if true, all labels must match to be enabled
- * @param {Array<string>} activeLabels Labels passed in through requestBids
- * @param {object} mediaTypes A mediaTypes object describing the various media types (banner, video, native)
- * @param {Array<Array<number>>} sizes Sizes specified on adUnit (deprecated)
- * @param {Array<SizeConfig>} configs
- * @returns {{labels: Array<string>, sizes: Array<Array<number>>}}
+ * Resolves the unique set of the union of all sizes and labels that are active from a SizeConfig.mediaQuery match.
+ *
+ * @param {Object} options - The options object.
+ * @param {Array<string>} [options.labels=[]] - Labels specified on adUnit or bidder.
+ * @param {boolean} [options.labelAll=false] - If true, all labels must match to be enabled.
+ * @param {Array<string>} [options.activeLabels=[]] - Labels passed in through requestBids.
+ * @param {Object} mediaTypes - A mediaTypes object describing the various media types (banner, video, native).
+ * @param {Array<SizeConfig>} configs - An array of SizeConfig objects.
+ * @returns {Object} - An object containing the active status, media types, and filter results.
+ * @returns {boolean} return.active - Whether the media types are active.
+ * @returns {Object} return.mediaTypes - The media types object.
+ * @returns {Object} [return.filterResults] - The filter results before and after applying size filtering.
  */
 export function resolveStatus({labels = [], labelAll = false, activeLabels = []} = {}, mediaTypes, configs = sizeConfig) {
   let maps = evaluateSizeConfig(configs);

modules/topicsFpdModule.js

@@ -201,7 +201,8 @@ export function receiveMessage(evt) {
 
 /**
 Function to store Topics data received from iframe in storage(name: "prebid:topics")
- * @param {Topics} topics
+ * @param {string} bidder
+ * @param {object} topics
  */
 export function storeInLocalStorage(bidder, topics) {
   const storedSegments = new Map(safeJSONParse(coreStorage.getDataFromLocalStorage(topicStorageName)));

modules/uid2IdSystem.js

@@ -69,7 +69,7 @@ export const uid2IdSubmodule = {
   /**
    * performs action to obtain id and return a value.
    * @function
-   * @param {SubmoduleConfig} [configparams]
+   * @param {SubmoduleConfig} config
    * @param {ConsentData|undefined} consentData
    * @returns {uid2Id}
    */

src/utils.js

@@ -382,7 +382,8 @@ export function isEmptyStr(str) {
  * Iterate object with the function
  * falls back to es5 `forEach`
  * @param {Array|Object} object
- * @param {Function(value, key, object)} fn
+ * @param {Function} fn - The function to execute for each element. It receives three arguments: value, key, and the original object.
+ * @returns {void}
  */
 export function _each(object, fn) {
   if (isFn(object?.forEach)) return object.forEach(fn, this);
@@ -397,7 +398,7 @@ export function contains(a, obj) {
  * Map an array or object into another array
  * given a function
  * @param {Array|Object} object
- * @param {Function(value, key, object)} callback
+ * @param {Function} callback - The function to execute for each element. It receives three arguments: value, key, and the original object.
  * @return {Array}
  */
 export function _map(object, callback) {
@@ -500,7 +501,6 @@ export function insertHtmlIntoIframe(htmlCode) {
 /**
  * Inserts empty iframe with the specified `url` for cookie sync
  * @param  {string} url URL to be requested
- * @param  {string} encodeUri boolean if URL should be encoded before inserted. Defaults to true
  * @param  {function} [done] an optional exit callback, used when this usersync pixel is added during an async process
  * @param  {Number} [timeout] an optional timeout in milliseconds for the iframe to load before calling `done`
  */
@@ -737,7 +737,6 @@ export function delayExecution(func, numRequiredCalls) {
 
 /**
  * https://stackoverflow.com/a/34890276/428704
- * @export
  * @param {Array} xs
  * @param {string} key
  * @returns {Object} {${key_value}: ${groupByArray}, key_value: {groupByArray}}
@@ -953,9 +952,9 @@ export function buildUrl(obj) {
  * This function deeply compares two objects checking for their equivalence.
  * @param {Object} obj1
  * @param {Object} obj2
- * @param checkTypes {boolean} if set, two objects with identical properties but different constructors will *not*
- * be considered equivalent.
- * @returns {boolean}
+ * @param {Object} [options] - Options for comparison.
+ * @param {boolean} [options.checkTypes=false] - If set, two objects with identical properties but different constructors will *not* be considered equivalent.
+ * @returns {boolean} - Returns `true` if the objects are equivalent, `false` otherwise.
  */
 export function deepEqual(obj1, obj2, {checkTypes = false} = {}) {
   if (obj1 === obj2) return true;
@@ -1090,7 +1089,7 @@ export function memoize(fn, key = function (arg) { return arg; }) {
 
 /**
  * Sets dataset attributes on a script
- * @param {Script} script
+ * @param {HTMLScriptElement} script
  * @param {object} attributes
  */
 export function setScriptAttributes(script, attributes) {

src/utils/perfMetrics.js

@@ -63,9 +63,9 @@ export function metricsFactory({now = getTime, mkNode = makeNode, mkTimer = make
       /**
        * Get the tame passed since `checkpoint`, and optionally save it as a metric.
        *
-       * @param checkpoint checkpoint name
-       * @param metric? metric name
-       * @return {number} time between now and `checkpoint`
+       * @param {string} checkpoint checkpoint name
+       * @param {string} [metric] - The name of the metric to save. Optional.
+       * @returns {number|null} - The time in milliseconds between now and the checkpoint, or `null` if the checkpoint is not found.
        */
       function timeSince(checkpoint, metric) {
         const ts = getTimestamp(checkpoint);
@@ -79,10 +79,10 @@ export function metricsFactory({now = getTime, mkNode = makeNode, mkTimer = make
       /**
        * Get the time passed between `startCheckpoint` and `endCheckpoint`, optionally saving it as a metric.
        *
-       * @param startCheckpoint begin checkpoint
-       * @param endCheckpoint end checkpoint
-       * @param metric? metric name
-       * @return {number} time passed between `startCheckpoint` and `endCheckpoint`
+       * @param {string} startCheckpoint - The name of the starting checkpoint.
+       * @param {string} endCheckpoint - The name of the ending checkpoint.
+       * @param {string} [metric] - The name of the metric to save. Optional.
+       * @returns {number|null} - The time in milliseconds between `startCheckpoint` and `endCheckpoint`, or `null` if either checkpoint is not found.
        */
       function timeBetween(startCheckpoint, endCheckpoint, metric) {
         const start = getTimestamp(startCheckpoint);
@@ -128,25 +128,25 @@ export function metricsFactory({now = getTime, mkNode = makeNode, mkTimer = make
       }
 
       /**
-       * @typedef {function: T} HookFn
-       * @property {function(T): void} bail
+       * @typedef {Function} HookFn
+       * @property {Function(T): void} bail
        *
        * @template T
-       * @typedef {T: HookFn} TimedHookFn
-       * @property {function(): void} stopTiming
+       * @typedef {HookFn} TimedHookFn
+       * @property {Function(): void} stopTiming
        * @property {T} untimed
        */
 
       /**
        * Convenience method for measuring time spent in a `.before` or `.after` hook.
        *
        * @template T
-       * @param name metric name
-       * @param {HookFn} next the hook's `next` (first) argument
-       * @param {function(TimedHookFn): T} fn a function that will be run immediately; it takes `next`,
+       * @param {string} name - The metric name.
+       * @param {HookFn} next - The hook's `next` (first) argument.
+       * @param {function(TimedHookFn): T} fn - A function that will be run immediately; it takes `next`,
        *    where both `next` and `next.bail` automatically
        *    call `stopTiming` before continuing with the original hook.
-       * @return {T} fn's return value
+       * @return {T} - The return value of `fn`.
        */
       function measureHookTime(name, next, fn) {
         const stopTiming = startTiming(name);
@@ -208,10 +208,11 @@ export function metricsFactory({now = getTime, mkNode = makeNode, mkTimer = make
        * ```
        *
        *
-       * @param propagate if false, the forked metrics will not be propagated here
-       * @param stopPropagation if true, propagation from the new metrics is stopped here - instead of
-       *   continuing up the chain (if for example these metrics were themselves created through `.fork()`)
-       * @param includeGroups if true, the forked metrics will also replicate metrics that were propagated
+       * @param {Object} [options={}] - Options for forking the metrics.
+       * @param {boolean} [options.propagate=true] - If false, the forked metrics will not be propagated here.
+       * @param {boolean} [options.stopPropagation=false] - If true, propagation from the new metrics is stopped here, instead of
+       *   continuing up the chain (if for example these metrics were themselves created through `.fork()`).
+       * @param {boolean} [options.includeGroups=false] - If true, the forked metrics will also replicate metrics that were propagated
        *   here from elsewhere. For example:
        *   ```
        *   const metrics = newMetrics();
@@ -222,6 +223,7 @@ export function metricsFactory({now = getTime, mkNode = makeNode, mkTimer = make
        *   withoutGroups.getMetrics() // {}
        *   withGroups.getMetrics() // {foo: ['bar']}
        *   ```
+       * @returns {Object} - The new metrics object.
        */
       function fork({propagate = true, stopPropagation = false, includeGroups = false} = {}) {
         return makeMetrics(mkNode([[self, {propagate, stopPropagation, includeGroups}]]), rename);