Add JSDoc comments to data generation scripts and output files

data/functions/generate_average_co2.js

@@ -1,16 +1,43 @@
+/**
+ * @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 +54,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 +68,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,24 +112,48 @@ const type = "average";
     };
   });
 
-  // This saves the country code and emissions data only, for use in the CO2.js library
+  const jsDocComments = `/**
+ * @fileoverview Minified average CO2 emissions intensity data for countries.
+ * @generated Generated by generate_average_co2.js
+ * @version 1.0.0
+*/
+
+/**
+ * @constant {Object.<string, number>} data - Average CO2 emissions intensity data for various countries.
+ * @constant {string} type - Type of data being represented.
+ */`;
+
+  /**
+   * 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 };`
+    `${jsDocComments} 
+    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, "  ")
   );
-})();
+})();

data/functions/generate_marginal_co2.js

@@ -1,17 +1,66 @@
+/**
+ * @fileoverview This script generates marginal CO2 emissions intensity data for countries using UNFCCC data.
+ * It processes the data from a CSV file and saves it in various formats for use in the CO2.js library.
+ * @author Chris Adams
+ * @version 1.0.0
+ */
+
 const fs = require("fs");
+
+/**
+ * Reads the UNFCCC CSV file containing grid factors data.
+ * @type {Buffer}
+ */
 const csv = fs.readFileSync(
   "data/IFI_Default_Grid_Factors_2021_v3.1_unfccc.csv"
 );
+
+/**
+ * Utility function to parse CSV rows.
+ * @type {function}
+ */
 const parseCSVRow = require("../utils/parseCSVRow");
+
+/**
+ * Utility function to get country codes.
+ * @type {function}
+ */
 const getCountryCodes = require("../utils/getCountryCodes");
+
+/**
+ * The type of intensity data being processed (marginal).
+ * @constant {string}
+ */
 const type = "marginal";
+
+/**
+ * The source of the data (UNFCCC).
+ * @constant {string}
+ */
 const source = "UNFCCC";
+
+/**
+ * The year of the data.
+ * @constant {string}
+ */
 const year = "2021";
 
+/**
+ * Converts the CSV data to an array of strings, each representing a row.
+ * @type {string[]}
+ */
 const array = csv.toString().split("\n");
 
-/* Store the converted result into an array */
+/**
+ * Object to store the converted CSV data.
+ * @type {Object.<string, Object>}
+ */
 const csvToJsonResult = {};
+
+/**
+ * Object to store the grid intensity results for each country.
+ * @type {Object.<string, string>}
+ */
 const gridIntensityResults = {};
 
 /* Store the CSV column headers into seprate variable */
@@ -79,20 +128,45 @@ for (let currentArrayString of array.slice(5)) {
 const json = JSON.stringify(csvToJsonResult);
 const gridIntensityJson = JSON.stringify(gridIntensityResults);
 
-// This saves the country code and emissions data only, for use in the CO2.js library
+const jsDocComments = `/**
+ * @fileoverview Minified marginal CO2 emissions intensity data for countries (2021).
+ * @generated Generated by generate_marginal_co2.js
+ * @version 1.0.0
+ */
+
+/**
+ * @constant {Object.<string, number>} data - Average CO2 emissions intensity data for various countries.
+ * @constant {string} type - Type of data being represented.
+ * @constant {string} year - Year for which the data was collected.
+ */`;
+
+/**
+ * Saves the country code and emissions data for use in the CO2.js library.
+ * @type {void}
+ */
 fs.writeFileSync(
   "data/output/marginal-intensities-2021.js",
-  `const data = ${gridIntensityJson}; 
+  `
+  const data = ${gridIntensityJson}; 
   const type = "${type}";
-const year = "${year}";
-export { data, type, year }; 
-export default { data, type, year };`
+  const year = "${year}";
+  export { data, type, year }; 
+  export default { data, type, year };
+  `
 );
-// 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/marginal-intensities-2021.min.js",
-  `const data = ${gridIntensityJson}; const type = "${type}"; const year = "${year}"; export { data, type, year }; export default { data, type, year };`
+  `${jsDocComments}
+  const data = ${gridIntensityJson}; const type = "${type}"; const year = "${year}"; export { data, type, year }; export default { data, type, year };`
 );
 
-// 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/marginal-intensities-2021.json", json);