diff --git a/modules/gamAdServerSubmodule.js b/modules/gamAdServerSubmodule.js index e2d01e6f21c..ec6c9d7b8e7 100644 --- a/modules/gamAdServerSubmodule.js +++ b/modules/gamAdServerSubmodule.js @@ -1,6 +1,11 @@ import { GAM_VENDOR } from './videoModule/constants/vendorCodes.js'; import { adServerDirectory } from './videoModule/vendorDirectory.js'; +/** + * @constructor + * @param {Object} dfpModule_ - the DFP ad server module + * @returns {AdServerProvider} + */ function GamAdServerProvider(dfpModule_) { const dfp = dfpModule_; diff --git a/modules/jwplayerVideoProvider.js b/modules/jwplayerVideoProvider.js index 8388d93554d..e6dab564564 100644 --- a/modules/jwplayerVideoProvider.js +++ b/modules/jwplayerVideoProvider.js @@ -11,6 +11,16 @@ import stateFactory from './videoModule/shared/state.js'; import { JWPLAYER_VENDOR } from './videoModule/constants/vendorCodes.js'; import { videoVendorDirectory } from './videoModule/vendorDirectory.js'; +/** + * @constructor + * @param {videoProviderConfig} config + * @param {Object} jwplayer_ - JW Player global factory + * @param {State} adState_ + * @param {State} timeState_ + * @param {CallbackStorage} callbackStorage_ + * @param {Object} utils + * @returns {VideoProvider} + */ export function JWPlayerProvider(config, jwplayer_, adState_, timeState_, callbackStorage_, utils) { const jwplayer = jwplayer_; let player = null; @@ -633,6 +643,10 @@ export function JWPlayerProvider(config, jwplayer_, adState_, timeState_, callba } } +/** + * @param {videoProviderConfig} config + * @returns {VideoProvider} + */ const jwplayerSubmoduleFactory = function (config) { const adState = adStateFactory(); const timeState = timeStateFactory(); @@ -779,6 +793,17 @@ export const utils = { } } +/** + * Tracks which functions are attached to events + * @typedef CallbackStorage + * @function storeCallback + * @function getCallback + * @function clearStorage + */ + +/** + * @returns {CallbackStorage} + */ export function callbackStorageFactory() { let storage = {}; @@ -815,6 +840,9 @@ export function callbackStorageFactory() { // STATE +/** + * @returns {State} + */ export function adStateFactory() { const adState = Object.assign({}, stateFactory()); @@ -875,6 +903,9 @@ export function adStateFactory() { return adState; } +/** + * @returns {State} + */ export function timeStateFactory() { const timeState = Object.assign({}, stateFactory()); diff --git a/modules/videoModule/adServer.js b/modules/videoModule/adServer.js index 3c6ddf9c86c..bf92ab6edc4 100644 --- a/modules/videoModule/adServer.js +++ b/modules/videoModule/adServer.js @@ -1,14 +1,58 @@ import { adServerDirectory } from './vendorDirectory.js'; import { ParentModule, SubmoduleBuilder } from './shared/parentModule.js'; +/** + * Ad Server Provider interface. All submodules of Ad Server Core must adhere to this. + * @typedef {Object} AdServerProvider + * @function getAdTagUrl - Builds an ad tag URL for a Bid. + */ + +/** + * @function AdServerProvider#getAdTagUrl + * @param {Object} adUnit - the Ad Unit associated to the bid + * @param {string} baseAdTagUrl - Ad Tag onto which the targeting params of the bid can be appended. + * @returns {string} + */ + +/** + * Config used to indicate which Ad Server to use to obtain the video ad tag url. + * @typedef {Object} AdServerConfig + * @property {string} vendorCode - The identifier of the AdServer vendor (i.e. gam, adloox, etc). + * @property {string} baseAdTagUrl - Ad Tag onto which the targeting params of the bid can be appended. + * @property {Object|undefined} params: Optional configuration block specific to the Ad Server vendor. + */ + +/** + * Routes commands to the appropriate Ad Server Submodule + * @typedef {Object} AdServerCore + * @function registerAdServer + * @function getAdTagUrl + */ + +/** + * @constructor + * @param {ParentModule} parentModule_ + * @returns {AdServerCore} + */ export function AdServerCore(parentModule_) { const parentModule = parentModule_; + /** + * @name AdServerCore#registerAdServer + * @param {AdServerConfig} config + */ function registerAdServer(config) { const vendorCode = config.vendorCode; parentModule.registerSubmodule(vendorCode, vendorCode, config); } + /** + * Builds an ad tag URL for a Bid + * @name AdServerCore#getAdTagUrl + * @param {string} vendorCode - identifier of the Ad Server Provider type i.e. GAM + * @param {Object} adUnit - the Ad Unit associated to the bid + * @param {string} baseAdTagUrl - Ad Tag onto which the targeting params of a bid can be appended + */ function getAdTagUrl(vendorCode, adUnit, baseAdTagUrl) { const submodule = parentModule.getSubmodule(vendorCode); return submodule && submodule.getAdTagUrl(adUnit, baseAdTagUrl); @@ -20,6 +64,11 @@ export function AdServerCore(parentModule_) { } } +/** + * @function coreAdServerFactory + * @summary Factory to create an instance of Core Ad Server + * @returns {AdServerCore} + */ export function coreAdServerFactory() { const adServerSubmoduleBuilder = SubmoduleBuilder(adServerDirectory); const parentModule = ParentModule(adServerSubmoduleBuilder); diff --git a/modules/videoModule/coreVideo.js b/modules/videoModule/coreVideo.js index 40944df9c64..458c098534b 100644 --- a/modules/videoModule/coreVideo.js +++ b/modules/videoModule/coreVideo.js @@ -4,7 +4,7 @@ import { ParentModule, SubmoduleBuilder } from './shared/parentModule.js'; // define, ortb object, events /** - Video Provider Submodule interface to the Core Video module @VideoCore. + * Video Provider Submodule interface. All submodules of the Core Video module must adhere to this. * @description attached to a video player instance. * @typedef {Object} VideoProvider * @function init - Instantiates the Video Provider and the video player, if not already instantiated. @@ -58,7 +58,7 @@ import { ParentModule, SubmoduleBuilder } from './shared/parentModule.js'; * @name videoProviderConfig * @summary contains data indicating which submodule to create and which player instance to attach it to * @property {string} divId - unique identifier of the player instance - * @property {string} vendorCode - identifier of the Video Provider type + * @property {number} vendorCode - numeric identifier of the Video Provider type i.e. video.js or jwplayer * @property {playerConfig} playerConfig */ @@ -164,9 +164,9 @@ export function VideoCore(parentModule_) { } /** - * @typedef {function} videoCoreFactory + * @function videoCoreFactory * @summary Factory to create a Video Core instance - * @returns {VideoCore} - an instance of the Core Video module + * @returns {VideoCore} */ export function videoCoreFactory() { const videoSubmoduleBuilder = SubmoduleBuilder(videoVendorDirectory);