From eb4e9ff2144be97906390c108e512304344d6ee2 Mon Sep 17 00:00:00 2001
From: Malay Kumar <malaykumar2003@gmail.com>
Date: Sat, 12 Oct 2024 18:58:53 +0530
Subject: [PATCH] Add JsDoc comments to generate_average_co2

---
 data/functions/generate_average_co2.js | 74 +++++++++++++++++++++-----
 1 file changed, 60 insertions(+), 14 deletions(-)

diff --git a/data/functions/generate_average_co2.js b/data/functions/generate_average_co2.js
index 8161c139..afb89959 100644
--- a/data/functions/generate_average_co2.js
+++ b/data/functions/generate_average_co2.js
@@ -1,16 +1,46 @@
+/**
+ * @fileoverview This script generates average CO2 emissions intensity data for countries using the Ember API.
+ * It processes the data and saves it in various formats for use in the CO2.js library.
+ * @author Chris Adams
+ * @version 1.0.0
+ */
+
 const fs = require("fs");
 
-// This URL from Ember returns ALL the data for the country_overview_yearly table
+/**
+ * The URL for the Ember API that provides country overview data on a yearly basis.
+ * @constant {string}
+ */
 const sourceURL =
   "https://ember-data-api-scg3n.ondigitalocean.app/ember/country_overview_yearly.json?_sort=rowid&_shape=array";
+
+
+/**
+ * Object to store the grid intensity results for each country.
+ * @type {Object.<string, number>}
+ */
 const gridIntensityResults = {};
+
+
+/**
+ * Object to store general results including additional country information.
+ * @type {Object.<string, Object>}
+ */
 const generalResults = {};
+
+
+/**
+ * The type of intensity data being processed (average or marginal).
+ * @constant {string}
+ */
 const type = "average";
 
 /**
- * This function generates the average CO2 emissions data for each country.
- * It reads the data from the Ember API and saves it in the data/output folder.
- * It also saves the data as a minified file in the src/data folder, so that it can be imported into the library.
+ * Fetches data from the Ember API, processes it to extract the latest average CO2 emissions
+ * intensity data for each country, and saves the results in various formats.
+ * @async
+ * @function
+ * @returns {Promise<void>}
  */
 
 // Use async/await
@@ -27,7 +57,10 @@ const type = "average";
   const response = await fetch(sourceURL);
   const data = await response.json();
 
-  // Group data by country_code
+  /**
+   * Groups the API data by country code.
+   * @type {Object.<string, Array>}
+   */
   const groupedData = await data.reduce((acc, item) => {
     const key =
       item.country_code === "" ? item.country_or_region : item.country_code;
@@ -38,7 +71,10 @@ const type = "average";
     return acc;
   }, {});
 
-  // Loop through the grouped data and find the latest year
+  /**
+   * Extracts the latest year's data for each country.
+   * @type {Object.<string, Object>}
+   */
   const latestData = await Object.keys(groupedData).reduce((acc, key) => {
     // Find the last year in the array with emissions intensity data
     const latestYear = groupedData[key].reduce((acc, item, index) => {
@@ -79,22 +115,32 @@ const type = "average";
     };
   });
 
-  // This saves the country code and emissions data only, for use in the CO2.js library
+  /**
+   * Saves the country code and emissions data for use in the CO2.js library.
+   * @type {void}
+   */
   fs.writeFileSync(
     "data/output/average-intensities.js",
-    `const data = ${JSON.stringify(gridIntensityResults, null, "  ")}; 
-const type = "${type}";
-export { data, type }; 
-export default { data, type };
-`
+    `
+    const data = ${JSON.stringify(gridIntensityResults, null, "  ")}; 
+    const type = "${type}";
+    export { data, type }; 
+    export default { data, type };
+    `
   );
-  // Save a minified version to the src folder so that it can be easily imported into the library
+  /**
+   * Saves a minified version of the data for easy import into the library.
+   * @type {void}
+   */
   fs.writeFileSync(
     "src/data/average-intensities.min.js",
     `const data = ${JSON.stringify(gridIntensityResults)}; const type = "${type}"; export { data, type }; export default { data, type };`
   );
 
-  // This saves the full data set as a JSON file for reference.
+  /**
+   * Saves the full data set as a JSON file for reference.
+   * @type {void}
+   */
   fs.writeFileSync(
     "data/output/average-intensities.json",
     JSON.stringify(generalResults, null, "  ")