Squashed commit of the following:

commit 668d8e4 Merge: 33c66d7 21a1a25 Author: fershad <[email protected]> Date: Wed Oct 23 10:15:46 2024 +0200 Add JSDoc comments to data generation scripts and output files commit 21a1a25 Author: fershad <[email protected]> Date: Wed Oct 23 16:11:01 2024 +0800 add comments to output of generators commit cab18cf Author: fershad <[email protected]> Date: Wed Oct 23 16:05:24 2024 +0800 add comments about constants in source files commit 33c66d7 Author: fershad <[email protected]> Date: Mon Oct 14 15:46:00 2024 +0800 add note about commenting commit 5e58971 Author: Malay Kumar <[email protected]> Date: Sat Oct 12 19:01:39 2024 +0530 Add JsDoc comments to marginal-intensities-2021 commit 6b000a0 Author: Malay Kumar <[email protected]> Date: Sat Oct 12 19:01:19 2024 +0530 Add JsDoc comments to average-intensities commit 29b6755 Author: Malay Kumar <[email protected]> Date: Sat Oct 12 18:59:08 2024 +0530 Add JsDoc comments to generate_marginal_co2 commit eb4e9ff Author: Malay Kumar <[email protected]> Date: Sat Oct 12 18:58:53 2024 +0530 Add JsDoc comments to generate_average_co2 commit c238d96 Author: fershad <[email protected]> Date: Wed Sep 11 10:30:41 2024 +0800 v0.16.1 commit d5d3156 Author: fershad <[email protected]> Date: Tue Sep 10 15:44:34 2024 +0800 0.16.1 commit 4b10930 Author: fershad <[email protected]> Date: Tue Sep 10 15:43:51 2024 +0800 v0.16.1 commit 8339284 Author: fershad <[email protected]> Date: Tue Sep 10 15:38:33 2024 +0800 update jsr export commit 6c0f991 Merge: 8f9097c ed2d8ab Author: fershad <[email protected]> Date: Tue Sep 10 15:35:05 2024 +0800 Add basic JSR support commit ed2d8ab Author: fershad <[email protected]> Date: Tue Sep 10 15:20:27 2024 +0800 update average grid intensities commit 8f9097c Author: fershad <[email protected]> Date: Tue Sep 10 15:17:29 2024 +0800 update test constants commit ce1ada5 Author: fershad <[email protected]> Date: Tue Sep 10 15:11:41 2024 +0800 update version commit 2962ca1 Author: fershad <[email protected]> Date: Tue Sep 10 15:06:52 2024 +0800 create hosting module commit 2dd34ec Author: fershad <[email protected]> Date: Tue Sep 10 15:03:33 2024 +0800 add mod.ts for jsr commit 870e621 Merge: 7adac52 87d0e62 Author: fershad <[email protected]> Date: Fri Sep 6 14:35:09 2024 +0800 [AUTOMATED] Update average annual grid intensities commit 87d0e62 Author: fershad <[email protected]> Date: Tue Sep 3 10:10:55 2024 +0000 Update average annual grid intensities commit 7adac52 Author: fershad <[email protected]> Date: Wed Aug 21 12:55:39 2024 +0800 update test constant commit 344a513 Merge: 4541319 d080a36 Author: fershad <[email protected]> Date: Wed Aug 14 21:36:04 2024 +0200 [AUTOMATED] Update average annual grid intensities commit d080a36 Author: fershad <[email protected]> Date: Sat Aug 3 10:09:23 2024 +0000 Update average annual grid intensities commit 4541319 Merge: 8f95399 c19da59 Author: fershad <[email protected]> Date: Wed Jul 31 22:38:58 2024 +0200 Export classes inside of the individual models commit c19da59 Author: fershad <[email protected]> Date: Thu Jul 11 22:02:57 2024 +0100 export classes inside of the CO2 class
alexzurbonsen · Oct 23, 2024 · e535f1b · e535f1b
1 parent 2474b1c
commit e535f1b
Show file tree

Hide file tree

Showing 16 changed files with 289 additions and 123 deletions.
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
@@ -9,17 +9,17 @@ Thank you for considering contributing to CO2.js. Open source is at the heart of
 **NB** Changes/commits that are not linked to an issue will not be accepted.
 
 ### New issues
-  - Our issue template provides you with a scaffold to follow when raising a new issue. There are three formats to choose from:
-    1. *Bugs* - clearly describe the problem you're facing including steps to reproduce it. Please also be sure to include the information about the environment your code was running in (e.g. NodeJS, Deno, Edge Worker, Browser etc).
-    1. *New features* - clearly describe the new feature you'd like to see added and provide a reason for why it should be added. eg what will be improved/possible as a result of making your suggested change.
-    1. *Request addition of carbon estimation model to CO2.js* - please provide as much information about the model as possible including links to additional documentation and information about how the model is licensed. 
-
 
+- Our issue template provides you with a scaffold to follow when raising a new issue. There are three formats to choose from:
+  1. _Bugs_ - clearly describe the problem you're facing including steps to reproduce it. Please also be sure to include the information about the environment your code was running in (e.g. NodeJS, Deno, Edge Worker, Browser etc).
+  1. _New features_ - clearly describe the new feature you'd like to see added and provide a reason for why it should be added. eg what will be improved/possible as a result of making your suggested change.
+  1. _Request addition of carbon estimation model to CO2.js_ - please provide as much information about the model as possible including links to additional documentation and information about how the model is licensed.
 
 ## Making Changes
 
 - Fork the repository on GitHub.
 - Create a topic branch from where you want to base your work. This branch should usually be based off `main`.
+- Remember to add JSDoc comments to any new functions or variables that you are introducing into the codebase.
 - Make commits of logical units.
 - Make commit messages clear and understandable.
 
@@ -28,10 +28,10 @@ Thank you for considering contributing to CO2.js. Open source is at the heart of
 - Push the changes made in your branch to your fork of this repository.
 - Submit a [pull request](https://github.com/thegreenwebfoundation/co2.js/pulls) to the CO2.js repository in the `thegreenwebfoundation` organization.
   - When opening a new pull request, you'll see a template. Please follow it. It asks you to state:
-      - the type of change (choose from a list)
-      - link to the related issue
-      - what documentation needs updating as a result (choose from a list)
-      - what your changes are - be sure to clearly explain the changes you've made, any new files, dependencies, or network requests that have been added, and provide any additional context to help reviewers understand the changes made.
+    - the type of change (choose from a list)
+    - link to the related issue
+    - what documentation needs updating as a result (choose from a list)
+    - what your changes are - be sure to clearly explain the changes you've made, any new files, dependencies, or network requests that have been added, and provide any additional context to help reviewers understand the changes made.
 - Your pull request will be reviewed by a maintainer from Green Web Foundation.
 - After feedback has been given we expect responses within two weeks. After two weeks we may close the pull request if it isn't showing any activity.
 
@@ -43,4 +43,4 @@ Please note that this project is released with a [Contributor Code of Conduct](h
 
 ## Thank you
 
-Again, thank you for your contributions. We appreciate your help improving CO2.js, and we look forward to your future contributions!
+Again, thank you for your contributions. We appreciate your help improving CO2.js, and we look forward to your future contributions!
diff --git a/data/functions/generate_average_co2.js b/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
@@ -31,7 +58,10 @@ const type = "average";
     }
     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;
@@ -42,7 +72,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) => {
@@ -87,7 +120,20 @@ const type = "average";
     fs.mkdirSync("data/output", { recursive: true });
     fs.mkdirSync("src/data", { recursive: true });
 
-    // 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, "  ")}; 
@@ -96,18 +142,28 @@ const type = "average";
       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, "  ")
     );
   } catch (error) {
     console.error("Error fetching or processing data:", error);
   }
-})();
+})();
diff --git a/data/functions/generate_marginal_co2.js b/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);