Core: add eslint-plugin-jsdoc

.eslintrc.js

@@ -11,12 +11,25 @@ module.exports = {
       node: {
         moduleDirectory: ['node_modules', './']
       }
+    },
+    'jsdoc': {
+      mode: 'typescript',
+      tagNamePreference: {
+        'tag constructor': 'constructor',
+        extends: 'extends',
+        method: 'method',
+        return: 'return',
+      }
     }
   },
-  extends: 'standard',
+  extends: [
+    'standard',
+    'plugin:jsdoc/recommended'
+  ],
   plugins: [
     'prebid',
-    'import'
+    'import',
+    'jsdoc'
   ],
   globals: {
     'BROWSERSTACK_USERNAME': false,
@@ -46,6 +59,24 @@ module.exports = {
     'no-undef': 2,
     'no-useless-escape': 'off',
     'no-console': 'error',
+    'jsdoc/check-types': 'off',
+    'jsdoc/newline-after-description': 'off',
+    'jsdoc/require-jsdoc': 'off',
+    'jsdoc/require-param': 'off',
+    'jsdoc/require-param-description': 'off',
+    'jsdoc/require-param-name': 'off',
+    'jsdoc/require-param-type': 'off',
+    'jsdoc/require-property': 'off',
+    'jsdoc/require-property-description': 'off',
+    'jsdoc/require-property-name': 'off',
+    'jsdoc/require-property-type': 'off',
+    'jsdoc/require-returns': 'off',
+    'jsdoc/require-returns-check': 'off',
+    'jsdoc/require-returns-description': 'off',
+    'jsdoc/require-returns-type': 'off',
+    'jsdoc/require-yields': 'off',
+    'jsdoc/require-yields-check': 'off',
+    'jsdoc/tag-lines': 'off'
   },
   overrides: Object.keys(allowedModules).map((key) => ({
     files: key + '/**/*.js',

modules/adagioAnalyticsAdapter.js

@@ -48,7 +48,7 @@ const enc = window.encodeURIComponent;
 
 /**
 /* BEGIN ADAGIO.JS CODE
-*/
+ */
 
 function canAccessTopWindow() {
   try {
@@ -71,12 +71,12 @@ const adagioEnqueue = function adagioEnqueue(action, data) {
 };
 
 /**
-* END ADAGIO.JS CODE
-*/
+ * END ADAGIO.JS CODE
+ */
 
 /**
-* UTILS FUNCTIONS
-*/
+ * UTILS FUNCTIONS
+ */
 
 const guard = {
   adagio: (value) => isAdagio(value),
@@ -130,9 +130,9 @@ function addKeyPrefix(obj, prefix) {
 }
 
 /**
-* sendRequest to Adagio. It filter null values and encode each query param.
-* @param {Object} qp
-*/
+ * sendRequest to Adagio. It filter null values and encode each query param.
+ * @param {Object} qp
+ */
 function sendRequest(qp) {
   // Removing null values
   qp = Object.keys(qp).reduce((acc, key) => {
@@ -164,7 +164,7 @@ function getTargetedAuctionId(bid) {
 
 /**
  * END UTILS FUNCTIONS
-*/
+ */
 
 /**
  * HANDLERS
@@ -175,7 +175,7 @@ function getTargetedAuctionId(bid) {
  * - handlerAdRender
  *
  * Each handler is called when the event is fired.
-*/
+ */
 
 function handlerAuctionInit(event) {
   const w = getCurrentWindow();
@@ -271,7 +271,7 @@ function handlerAuctionInit(event) {
  * handlerBidResponse allow to track the adagio bid response
  * and to update the auction cache with the seat ID.
  * No beacon is sent here.
-*/
+ */
 function handlerBidResponse(event) {
   if (!guard.adagio(event.bidder)) {
     return;
@@ -372,7 +372,7 @@ function handlerAdRender(event, isSuccess) {
 
 /**
  * END HANDLERS
-*/
+ */
 
 let adagioAdapter = Object.assign(adapter({ emptyUrl, analyticsType }), {
   track: function(event) {

modules/adagioBidAdapter.js

@@ -700,9 +700,9 @@ function getPageDimensions() {
 }
 
 /**
-* @todo Move to prebid Core as Utils.
-* @returns
-*/
+ * @todo Move to prebid Core as Utils.
+ * @returns
+ */
 function getViewPortDimensions() {
   if (!isSafeFrameWindow() && !canAccessTopWindow()) {
     return '';
@@ -832,8 +832,8 @@ function getPrintNumber(adUnitCode, bidderRequest) {
 }
 
 /**
-  * domLoading feature is computed on window.top if reachable.
-  */
+ * domLoading feature is computed on window.top if reachable.
+ */
 function getDomLoadingDuration() {
   let domLoadingDuration = -1;
   let performance;

modules/admaticBidAdapter.js

@@ -33,7 +33,8 @@ export const spec = {
     {code: 'pixad'}
   ],
   supportedMediaTypes: [BANNER, VIDEO, NATIVE],
-  /** f
+  /**
+   * f
    * @param {object} bid
    * @return {boolean}
    */

modules/adpod.js

@@ -319,7 +319,7 @@ export function checkAdUnitSetupHook(fn, adUnits) {
  * @param {Object} videoMediaType 'mediaTypes.video' associated to bidResponse
  * @param {Object} bidResponse incoming bidResponse being evaluated by bidderFactory
  * @returns {boolean} return false if bid duration is deemed invalid as per adUnit configuration; return true if fine
-*/
+ */
 function checkBidDuration(videoMediaType, bidResponse) {
   const buffer = 2;
   let bidDuration = deepAccess(bidResponse, 'video.durationSeconds');

modules/adqueryBidAdapter.js

@@ -17,7 +17,8 @@ export const spec = {
   gvlid: ADQUERY_GVLID,
   supportedMediaTypes: [BANNER],
 
-  /** f
+  /**
+   * f
    * @param {object} bid
    * @return {boolean}
    */

modules/beopBidAdapter.js

@@ -23,11 +23,11 @@ export const spec = {
   gvlid: TCF_VENDOR_ID,
   aliases: ['bp'],
   /**
-    * Test if the bid request is valid.
-    *
-    * @param {bid} : The Bid params
-    * @return boolean true if the bid request is valid (aka contains a valid accountId or networkId and is open for BANNER), false otherwise.
-    */
+   * Test if the bid request is valid.
+   *
+   * @param {bid} : The Bid params
+   * @return boolean true if the bid request is valid (aka contains a valid accountId or networkId and is open for BANNER), false otherwise.
+   */
   isBidRequestValid: function(bid) {
     const id = bid.params.accountId || bid.params.networkId;
     if (id === null || typeof id === 'undefined') {
@@ -39,12 +39,12 @@ export const spec = {
     return bid.mediaTypes.banner !== null && typeof bid.mediaTypes.banner !== 'undefined';
   },
   /**
-    * Create a BeOp server request from a list of BidRequest
-    *
-    * @param {validBidRequests[], ...} : The array of validated bidRequests
-    * @param {... , bidderRequest} : Common params for each bidRequests
-    * @return ServerRequest Info describing the request to the BeOp's server
-    */
+   * Create a BeOp server request from a list of BidRequest
+   *
+   * @param {validBidRequests[], ...} : The array of validated bidRequests
+   * @param {... , bidderRequest} : Common params for each bidRequests
+   * @return ServerRequest Info describing the request to the BeOp's server
+   */
   buildRequests: function(validBidRequests, bidderRequest) {
     const slots = validBidRequests.map(beOpRequestSlotsMaker);
     const firstPartyData = bidderRequest.ortb2 || {};

modules/bliinkBidAdapter.js

@@ -134,8 +134,8 @@ function canAccessTopWindow() {
 }
 
 /**
-  * domLoading feature is computed on window.top if reachable.
-  */
+ * domLoading feature is computed on window.top if reachable.
+ */
 export function getDomLoadingDuration() {
   let domLoadingDuration = -1;
   let performance;

modules/blueconicRtdProvider.js

@@ -19,9 +19,9 @@ export const RTD_LOCAL_NAME = 'bcPrebidData';
 export const storage = getStorageManager({moduleType: MODULE_TYPE_RTD, moduleName: SUBMODULE_NAME});
 
 /**
-* Try parsing stringified array of data.
-* @param {String} data
-*/
+ * Try parsing stringified array of data.
+ * @param {String} data
+ */
 function parseJson(data) {
   try {
     return JSON.parse(data);

modules/brandmetricsRtdProvider.js

@@ -72,10 +72,10 @@ function checkConsent (userConsent) {
 }
 
 /**
-* Add event- listeners to hook in to brandmetrics events
-* @param {Object} reqBidsConfigObj
-* @param {function} callback
-*/
+ * Add event- listeners to hook in to brandmetrics events
+ * @param {Object} reqBidsConfigObj
+ * @param {function} callback
+ */
 function processBrandmetricsEvents (reqBidsConfigObj, moduleConfig, callback) {
   const callBidTargeting = (event) => {
     if (event.available && event.conf) {
@@ -139,8 +139,8 @@ function initializeBrandmetrics(scriptId) {
 }
 
 /**
-* Hook in to brandmetrics creative_in_view- event and emit billable- event for creatives measured by brandmetrics.
-*/
+ * Hook in to brandmetrics creative_in_view- event and emit billable- event for creatives measured by brandmetrics.
+ */
 function initializeBillableEvents() {
   if (!billableEventsInitialized) {
     window._brandmetrics.push({

modules/bucksenseBidAdapter.js

@@ -16,7 +16,7 @@ export const spec = {
    *
    * @param {object} bid The bid to validate.
    * @return boolean True if this is a valid bid, and false otherwise.
-  */
+   */
   isBidRequestValid: function (bid) {
     logInfo(WHO + ' isBidRequestValid() - INPUT bid:', bid);
     if (bid.bidder !== BIDDER_CODE || typeof bid.params === 'undefined') {
@@ -29,10 +29,10 @@ export const spec = {
   },
 
   /**
-    * Make a server request from the list of BidRequests.
-    *
-    * @param {BidRequest[]} validBidRequests A non-empty list of valid bid requests that should be sent to the Server.
-    * @return ServerRequest Info describing the request to the server.
+   * Make a server request from the list of BidRequests.
+   *
+   * @param {BidRequest[]} validBidRequests A non-empty list of valid bid requests that should be sent to the Server.
+   * @return ServerRequest Info describing the request to the server.
    */
   buildRequests: function (validBidRequests, bidderRequest) {
     logInfo(WHO + ' buildRequests() - INPUT validBidRequests:', validBidRequests, 'INPUT bidderRequest:', bidderRequest);
@@ -74,7 +74,7 @@ export const spec = {
    *
    * @param {*} serverResponse A successful response from the server.
    * @return {Bid[]} An array of bids which were nested inside the server.
-  */
+   */
   interpretResponse: function (serverResponse, request) {
     logInfo(WHO + ' interpretResponse() - INPUT serverResponse:', serverResponse, 'INPUT request:', request);
 

modules/codefuelBidAdapter.js

@@ -10,23 +10,23 @@ export const spec = {
   supportedMediaTypes: [ BANNER ],
   aliases: ['ex'], // short code
   /**
-         * Determines whether or not the given bid request is valid.
-         *
-         * @param {BidRequest} bid The bid params to validate.
-         * @return boolean True if this is a valid bid, and false otherwise.
-         */
+   * Determines whether or not the given bid request is valid.
+   *
+   * @param {BidRequest} bid The bid params to validate.
+   * @return boolean True if this is a valid bid, and false otherwise.
+   */
   isBidRequestValid: function(bid) {
     if (bid.nativeParams) {
       return false;
     }
     return !!(bid.params.placementId || (bid.params.member && bid.params.invCode));
   },
   /**
-         * Make a server request from the list of BidRequests.
-         *
-         * @param {validBidRequests[]} - an array of bids
-         * @return ServerRequest Info describing the request to the server.
-         */
+   * Make a server request from the list of BidRequests.
+   *
+   * @param {validBidRequests[]} - an array of bids
+   * @return ServerRequest Info describing the request to the server.
+   */
   buildRequests: function(validBidRequests, bidderRequest) {
     const page = bidderRequest.refererInfo.page;
     const domain = bidderRequest.refererInfo.domain;
@@ -78,11 +78,11 @@ export const spec = {
     };
   },
   /**
-         * Unpack the response from the server into a list of bids.
-         *
-         * @param {ServerResponse} serverResponse A successful response from the server.
-         * @return {Bid[]} An array of bids which were nested inside the server.
-         */
+   * Unpack the response from the server into a list of bids.
+   *
+   * @param {ServerResponse} serverResponse A successful response from the server.
+   * @return {Bid[]} An array of bids which were nested inside the server.
+   */
   interpretResponse: (serverResponse, { bids }) => {
     if (!serverResponse.body) {
       return [];
@@ -116,12 +116,12 @@ export const spec = {
   },
 
   /**
-     * Register the user sync pixels which should be dropped after the auction.
-     *
-     * @param {SyncOptions} syncOptions Which user syncs are allowed?
-     * @param {ServerResponse[]} serverResponses List of server's responses.
-     * @return {UserSync[]} The user syncs which should be dropped.
-     */
+   * Register the user sync pixels which should be dropped after the auction.
+   *
+   * @param {SyncOptions} syncOptions Which user syncs are allowed?
+   * @param {ServerResponse[]} serverResponses List of server's responses.
+   * @return {UserSync[]} The user syncs which should be dropped.
+   */
   getUserSyncs: function(syncOptions, serverResponses, gdprConsent, uspConsent) {
     return [];
   }

modules/criteoBidAdapter.js

@@ -125,7 +125,8 @@ export const spec = {
     return [];
   },
 
-  /** f
+  /**
+   * f
    * @param {object} bid
    * @return {boolean}
    */