Add JSDoc and comment changes (NR-85069) (#389)

Adds JSDoc blocks and comments, primarily related to architectural changes from PR 358.

Author: bjfield

babel-env-vars.js

@@ -1,8 +1,27 @@
+/**
+ * @file Derives a "version" for injection into the bundle. Used to configure Babel for NPM, Webpack, and test server.
+ */
+
 const pkg = require('./package.json')
 const fs = require('fs')
 
 const VERSION = fs.readFileSync('./VERSION', 'utf-8')
 
+/*
+ * Version injection is currently complicated by the fact that NPM will build with package.json.version while CDN will
+ * build with the value in the VERSION file, as well as subversion attributes such as PROD, DEV, LOCAL, etc. Once
+ * aligned, this process will be simpler.
+ */
+
+/**
+ * Derives a build version based on the specified source and subversion and assigns the value to a process environment
+ * variable called `BUILD_VERSION`.
+ * @param {string} source - The desired source of the version number. Can be `VERSION` or `PACKAGE`.
+ * @param {string} subversion - A build classification suffix (e.g. `PROD` or a PR number).
+ * @returns {Array} - A configuration array with plugin configuration for
+ *     `babel-plugin-transform-inline-environment-variables`.
+ * @see https://babeljs.io/docs/en/babel-plugin-transform-inline-environment-variables
+ */
 module.exports = (source, subversion) => {
   if (!process.env['BUILD_VERSION']) {
     if (source === 'VERSION') process.env['BUILD_VERSION'] = `${VERSION}.${subversion || 'LOCAL'}`

babel.npm.cjs.js

@@ -1,3 +1,7 @@
+/**
+ * @file Provides Babel configuration for compiling src/index.js into NPM package output (CommonJS).
+ */
+
 const babelEnv = require('./babel-env-vars')
 
 const presets = [

babel.npm.esm.js

@@ -1,3 +1,7 @@
+/**
+ * @file Provides Babel configuration for compiling src/index.js into NPM package output (ES modules).
+ */
+
 const babelEnv = require('./babel-env-vars')
 
 const presets = []

src/cdn/lite.js

@@ -1,3 +1,7 @@
+/**
+ * @file Creates a "Lite" agent loader bundle composed of the core Agent and a subset of available feature modules.
+ */
+
 import { Agent } from '../loaders/agent'
 
 import { Instrument as InstrumentPageViewEvent } from '../features/page_view_event/instrument'

src/cdn/polyfills.js

@@ -1,4 +1,8 @@
-/** IE9, IE10, IE11, and pre es6 browsers require some or all of the following polyfills. **/
+/**
+ * @file Selectively imports {@link https://github.com/zloirock/core-js core-js}
+ *     polyfills needed for pre-ES6 browsers and IE 11.
+ */
+
 import 'core-js/stable/promise'
 import 'core-js/stable/array/includes'
 import 'core-js/stable/array/from'
@@ -10,29 +14,3 @@ import 'core-js/stable/object/values'
 import 'core-js/stable/map'
 import 'core-js/stable/reflect'
 import 'core-js/stable/set'
-
-// promise
-// ie - none
-// safari - 7+
-// ios - 8+
-// chrome - 33+
-// edge - 12+
-// ff - 29+
-
-// not in use currently.... but be aware this feature of promises has much different benchmark support
-// promise.any, promise.allSettled
-// ie - none
-// safari - 14+
-// ios - 14+
-// chrome - 85+
-// edge - 105+
-// ff - 79+
-
-// making note because this feature of promises has different benchmark support
-// promise.any
-// ie - none
-// safari - 8
-// ios - 8+
-// chrome - 32+
-// edge - 12+
-// ff - 29+

src/cdn/polyfills/lite.js

@@ -1,2 +1,7 @@
+/**
+ * @file Creates a version of the "Lite" agent loader with [core-js]{@link https://github.com/zloirock/core-js}
+ * polyfills for pre-ES6 browsers and IE 11.
+ */
+
 import '../polyfills.js'
 import '../lite'

src/cdn/polyfills/pro.js

@@ -1,2 +1,7 @@
+/**
+ * @file Creates a version of the "Pro" agent loader with [core-js]{@link https://github.com/zloirock/core-js}
+ * polyfills for pre-ES6 browsers and IE 11.
+ */
+
 import '../polyfills.js'
 import '../pro'

src/cdn/polyfills/spa.js

@@ -1,2 +1,7 @@
+/**
+ * @file Creates a version of the "SPA" agent loader with [core-js]{@link https://github.com/zloirock/core-js}
+ * polyfills for pre-ES6 browsers and IE 11.
+ */
+
 import '../polyfills.js'
 import '../spa'

src/cdn/pro.js

@@ -1,3 +1,8 @@
+/**
+ * @file Creates a "Pro" agent loader bundle composed of the core Agent and all available feature modules except `spa`.
+ * This excludes collection of BrowserInteraction and BrowserTiming events.
+ */
+
 import { Agent } from '../loaders/agent'
 
 import { Instrument as InstrumentPageViewEvent } from '../features/page_view_event/instrument'

src/cdn/spa.js

@@ -1,3 +1,7 @@
+/**
+ * @file Creates a "SPA" agent loader bundle composed of the core agent and all available feature modules.
+ */
+
 import { Agent } from '../loaders/agent'
 
 import { Instrument as InstrumentPageViewEvent } from '../features/page_view_event/instrument'