docs(acms): Adds comments to the new helper functions

src/appellate/acms_api.js

@@ -1,4 +1,13 @@
 function Acms() {
+  // Asynchronously checks the progress of the PDF link generation using a
+  // provided URL and authorization token.
+  // This function fetches data from the specified URL using a GET request with
+  // an Authorization header containing a Bearer token. It then parses the JSON
+  // response and throws an error if the request fails (status code is not 200).
+  // Otherwise, it returns the parsed JSON data.
+  //
+  // returns A promise that resolves to the parsed JSON data
+  // on success, or rejects with an error if the request fails.
   async function checkProgress(url, token) {
     const response = await fetch(url, {
       headers: { Authorization: `Bearer ${token}` },
@@ -12,6 +21,17 @@ function Acms() {
     return data;
   }
 
+  // Asynchronously submits data to a server using a POST request.
+  // This function sends a POST request to the specified URL with an
+  // authorization token and the provided data.
+  // The data is expected to be a JavaScript object and will be converted
+  // to format before sending and The Authorization header includes a Bearer
+  // token for authentication. The function parses the JSON response and
+  // throws an error if the request fails (status code is not 200 OK).
+  // Otherwise, it returns the parsed JSON data.
+  //
+  // Returns A promise that resolves to the parsed JSON data on success, or
+  // rejects with an error if the request fails.
   async function postData(url, token, body = {}) {
     const response = await fetch(url, {
       method: 'POST',
@@ -30,6 +50,24 @@ function Acms() {
     return data;
   }
 
+  // This function simulates a while loop using Promises. It takes three
+  // arguments:
+  //  - `input`: The initial value for the loop.
+  //  - `condition`: A function that evaluates to true as long as the loop
+  //     should continue.
+  //  - `action`: A function that returns a Promise and performs the loop's
+  //     logic for each iteration.
+  //
+  // It returns a Promise that resolves with the final `input` value when the
+  // `condition` function becomes false.
+  //
+  // It works by defining a recursive helper function `whilst`. This function
+  // checks the `condition` on the current `input`.
+  //  - If `condition` is true, it calls the `action` function with `input`.
+  //    The result (a Promise) is then chained with another call to `whilst`,
+  //    effectively continuing the loop.
+  //  - If `condition` is false, it resolves the returned Promise immediately
+  //    with the current `input` value, signifying the end of the loop.
   const promiseWhile = (input, condition, action) => {
     const whilst = (input) =>
       condition(input) ? action(input).then(whilst) : Promise.resolve(input);
@@ -44,18 +82,26 @@ function Acms() {
 
       const statusQueryUrl = data && data.statusQueryGetUri;
 
+      // Prepare elements to be used within the promiseWhile loop.
+      // Helper function to check if the job is completed based on a
+      // given status
       const isCompleted = (status) => /Completed/i.test(status);
+      // Helper function to determine if we should continue checking
       const condition = (runtimeStatus) => !isCompleted(runtimeStatus);
+      // Initial runtime status (empty string)
       const initialRuntimeStatus = '';
 
+      // Function to perform a single check on the job progress
       const action = (runtimeStatus) =>
         new Promise((resolve, reject) => {
           checkProgress(statusQueryUrl, token)
             .then((response) => {
+              // Extract the new runtime status from the response (if it exists)
               const newRuntimeStatus = response && response.runtimeStatus;
 
               if (!newRuntimeStatus) reject('No runtime status was returned.');
 
+              // Update the output variable if the job is completed
               if (isCompleted(newRuntimeStatus))
                 output = response && response.output;
 
@@ -66,6 +112,7 @@ function Acms() {
             });
         });
 
+      // Use promiseWhile to keep checking the status until the job is completed
       let fileGuid = await promiseWhile(
         initialRuntimeStatus,
         condition,

src/appellate/appellate.js

@@ -134,6 +134,37 @@ AppellateDelegate.prototype.handleAcmsDocket = async function () {
 AppellateDelegate.prototype.handleAcmsDownloadPage = async function () {
 
   async function startUploadProcess() {
+    // This function initiates the upload process for a PDF document.
+    // It performs the following steps:
+    //
+    // 1. Prepares data for upload:
+    //    - Parses download data from session storage and creates a request
+    //      body for the PDF URL document.
+    //
+    // 2. Retrieves configuration and tokens:
+    //    - Extracts API URL and token from session storage stored in
+    //      the 'recapACMSConfiguration' key.
+    //
+    // 3. Extracts document information:
+    //    - Extracts title from the element with class 'p.font-weight-bold'.
+    //    - Parses relevant details (att_number) from the title.
+    //    - Builds a documentData object containing docket number, document
+    //      number, and attachment number.
+    //
+    // 4. Adds a loading message:
+    //    - Creates a loading message using APPELLATE.createsLoadingMessage.
+    //
+    // 5. Stores case ID and document GUID (assumed for later use):
+    //    - Saves case ID from download data.
+    //    - Saves document GUID from download data.
+    //
+    // 6. Gets PDF download URL and initiates download:
+    //    - Stores the current page HTML content.
+    //    - Calls acms.getDocumentURL to get the PDF download URL.
+    //    - Once the URL is retrieved, initiates an HTTP request to download
+    //      the PDF.
+    //    - Binds the handleDocFormResponse function to handle the downloaded
+    //      data and document information after download completes.
     let downloadData = JSON.parse(
       sessionStorage.getItem('recapVueData')
     );

src/appellate/utils.js

@@ -424,6 +424,13 @@ let APPELLATE = {
 
   // Adds the vue data attributes to the session storage
   storeVueDataInSession: () => {
+    // The following code draws inspiration from the Vue devtool extension
+    // to identify and inspect Vue components within a web application.
+    // Unlike the devtool extension, which explores the entire DOM, this script
+    // focuses on extracting the data of the main Vue component. By tailoring
+    // the script to the component's HTML structure, we achieve a quick data
+    // retrieval process compared to a full DOM exploration.
+    // The extracted data is then stored in session storage for later use.
     var code =
       '(' +
       function () {
@@ -451,7 +458,26 @@ let APPELLATE = {
     script.remove();
   },
 
-  // Extract data needed to construct the PDF request body
+  // Prepares the body to request a PDF document link
+  // It takes the `downloadData` object as input, which is expected to contain
+  // information about the documents to be included in the link
+  // The function performs the following actions:
+  // 1. Extracts query parameters from the URL to determine if page numbers
+  //    should be included.
+  // 2. Gets the value from the 'showPdfHeader' checkbox to determine if a
+  //    header should be included in the PDF.
+  // 3. Defines a helper function `pdfItemMapping` that extracts relevant data
+  //    from each document in `downloadData.docketEntryDocuments`.
+  // 4. Constructs the request body object with the following properties:
+  //     - `mergeScope`: Set to 'External' as these are external documents.
+  //     - `pagination`: Set to the value of `includePageNumbers` for including
+  //        page numbers.
+  //     - `header`: Set to the value of `showPDFHeaderInput` for including a
+  //        header.
+  //     - `docketEntryDocuments`: An array of objects containing mapped
+  //        document details using `pdfItemMapping`.
+  //
+  // This function returns the constructed request body object.
   createAcmsDocumentRequestBody: function (downloadData) {
     let queryParameters = new URLSearchParams(window.location.search);
     let includePageNumbers = !!queryParameters.get('includePageNumbers');