From 51ed1744a883e31a287e145a40d86fcf9e5239c7 Mon Sep 17 00:00:00 2001
From: Xinyi Feng <xfeng@adobe.com>
Date: Fri, 9 Aug 2024 10:34:19 -0700
Subject: [PATCH] add comments

---
 src/index.js | 59 +++++++++++++++++++++++++++++++++++++++++++++++-----
 1 file changed, 54 insertions(+), 5 deletions(-)

diff --git a/src/index.js b/src/index.js
index ccf7172..eea4ba8 100644
--- a/src/index.js
+++ b/src/index.js
@@ -10,6 +10,12 @@
  * governing permissions and limitations under the License.
  */
 
+/**
+ * Set isDebugEnabled accordingly based on the URL and plugin options.
+ * @param {Object} url window.location
+ * @param {Object} pluginOptions with default options and custom options
+ * @returns {Boolean} whether debug mode is enabled
+ */
 let isDebugEnabled;
 export function setDebugMode(url, pluginOptions) {
   const { host, hostname, origin } = url;
@@ -29,6 +35,11 @@ export function debug(...args) {
   }
 }
 
+/**
+ * Default options for the plugin.
+ * could be extended and overridden by passing custom options
+ * e.g. 'abtest' instead of 'experiment' by passing { experimentsMetaTagPrefix: 'abtest' } in custom options
+ */
 export const DEFAULT_OPTIONS = {
 
   // Audiences related properties
@@ -199,10 +210,11 @@ function getAllSectionMeta(block, scope) {
 }
 
 /**
- * Replaces element with content from path
- * @param {String} path
- * @param {HTMLElement} el
- * @return Returns the path that was loaded or null if the loading failed
+ * Replaces the inner content of an element with content from a specified path.
+ * @param {String} path - the url path to load the content from
+ * @param {HTMLElement} el - the element to replace the content of
+ * @param {String} selector - taget CSS selector for fragment replacement
+ * @return The path that was loaded or null if the loading failed
  */
 async function replaceInner(path, el, selector) {
   try {
@@ -516,6 +528,7 @@ async function applyAllModifications(
       }
     }));
 
+  // Fragment-level modifications
   if (pageMetadata.manifest) {
     let entries = await getManifestEntriesForCurrentPage(pageMetadata.manifest);
     if (entries) {
@@ -537,6 +550,12 @@ async function applyAllModifications(
   return configs;
 }
 
+/**
+ * Aggregates the entries into a single object.
+ * @param {String} type experiment, campaign or audience
+ * @param {String[]} allowedMultiValuesProperties properties that can have multiple values
+ * @returns object with the aggregated entries
+ */
 function aggregateEntries(type, allowedMultiValuesProperties) {
   return (entries) => entries.reduce((aggregator, entry) => {
     Object.entries(entry).forEach(([key, value]) => {
@@ -672,7 +691,9 @@ async function getExperimentConfig(pluginOptions, metadata, overrides) {
 }
 
 /**
- * Parses the campaign manifest.
+ * Parses the experiemnt manifest
+ * @param {Object} entries fragment manifest entries
+ * @returns {Object} parsed fragment manifest that grouped by experiment
  */
 function parseExperimentManifest(entries) {
   return Object.values(Object.groupBy(
@@ -687,6 +708,12 @@ function getUrlFromExperimentConfig(config) {
     : null;
 }
 
+/**
+ * Runs the experiment on page/section/fragment.
+ * Page and Section level modifications are applied immediately,
+ * while fragment level modifications will be watched by observer.
+ * And dispatches custom events for further handling if needed.
+ */
 async function runExperiment(document, pluginOptions) {
   return applyAllModifications(
     pluginOptions.experimentsMetaTagPrefix,
@@ -790,6 +817,12 @@ function getUrlFromCampaignConfig(config) {
     : null;
 }
 
+/**
+ * Runs the campaign on page/section/fragment.
+ * Page and Section level modifications are applied immediately,
+ * while fragment level modifications will be watched by observer.
+ * And dispatches custom events for further handling if needed.
+ */
 async function runCampaign(document, pluginOptions) {
   return applyAllModifications(
     pluginOptions.campaignsMetaTagPrefix,
@@ -872,6 +905,12 @@ function getUrlFromAudienceConfig(config) {
     : null;
 }
 
+/**
+ * Serves the audience on page/section/fragment.
+ * Page and Section level modifications are applied immediately,
+ * while fragment level modifications will be watched by observer.
+ * And dispatches custom events for further handling if needed.
+ */
 async function serveAudience(document, pluginOptions) {
   document.body.dataset.audiences = Object.keys(pluginOptions.audiences).join(',');
   return applyAllModifications(
@@ -901,6 +940,11 @@ async function serveAudience(document, pluginOptions) {
   );
 }
 
+/**
+ * Loads and initializes plugins and functionalities eagerly,
+ * @param {Document} document  The HTML document to be processed
+ * @param {Object} [options={}] Custom options passed from customer
+ */
 export async function loadEager(document, options = {}) {
   const pluginOptions = { ...DEFAULT_OPTIONS, ...options };
   setDebugMode(window.location, pluginOptions);
@@ -916,14 +960,19 @@ export async function loadEager(document, options = {}) {
   ns.campaign = ns.campaigns.find((e) => e.type === 'page');
 }
 
+/**
+ * Loads the experimentation pill when debug mode is enabled
+ */
 export async function loadLazy(document, options = {}) {
   const pluginOptions = { ...DEFAULT_OPTIONS, ...options };
   // do not show the experimentation pill on prod domains
   if (!isDebugEnabled) {
     return;
   }
+  // fetch the central-host preview script from github pages
   // eslint-disable-next-line import/no-unresolved
   const preview = await import('https://opensource.adobe.com/aem-experimentation/preview.js');
+  // functions to be passed to the preview script
   const context = {
     getMetadata,
     toClassName,