Update JSDocs to match behaviour of perVisitType and perByteType

thegreenwebfoundation · Apr 4, 2024 · a6f1d4d · a6f1d4d
2 parents 3756c74 + 5f46b50
commit a6f1d4d
Showing 1 changed file with 28 additions and 6 deletions.
diff --git a/src/co2.js b/src/co2.js
@@ -2,16 +2,16 @@
 
 /**
  * @typedef {Object} CO2EstimateTraceResultPerByte
- * @property {number} co2 - The CO2 estimate in grams/kilowatt-hour
+ * @property {number|CO2EstimateComponentsPerByte} co2 - The CO2 estimate in grams or its separate components
  * @property {boolean} green - Whether the domain is green or not
- * @property {TraceResultVariables} variables - The variables used to calculate the CO2 estimate
+ * @property {TraceResultVariablesPerByte} variables - The variables used to calculate the CO2 estimate
  */
 
 /**
  * @typedef {Object} CO2EstimateTraceResultPerVisit
- * @property {number} co2 - The CO2 estimate in grams/kilowatt-hour
+ * @property {number|CO2EstimateComponentsPerVisit} co2 - The CO2 estimate in grams or its separate components
  * @property {boolean} green - Whether the domain is green or not
- * @property {TraceResultVariables} variables - The variables used to calculate the CO2 estimate
+ * @property {TraceResultVariablesPerVisit} variables - The variables used to calculate the CO2 estimate
  */
 
 /**
@@ -35,6 +35,28 @@
  * @property {number} production - The production grid intensity set by the user or the default
  */
 
+/**
+ * @typedef {Object} CO2EstimateComponentsPerByte
+ * @property {number} networkCO2 - The CO2 estimate for networking in grams
+ * @property {number} dataCenterCO2 - The CO2 estimate for data centers in grams
+ * @property {number} consumerDeviceCO2 - The CO2 estimate for consumer devices in grams
+ * @property {number} productionCO2 - The CO2 estimate for device production in grams
+ * @property {number} total - The total CO2 estimate in grams
+ */
+
+/**
+ * @typedef {Object} CO2EstimateComponentsPerVisit
+ * @property {number} 'networkCO2 - first' - The CO2 estimate for networking in grams on first visit
+ * @property {number} 'networkCO2 - subsequent' - The CO2 estimate for networking in grams on subsequent visits
+ * @property {number} 'dataCenterCO2 - first' - The CO2 estimate for data centers in grams on first visit
+ * @property {number} 'dataCenterCO2 - subsequent' - The CO2 estimate for data centers in grams on subsequent visits
+ * @property {number} 'consumerDeviceCO2 - first' - The CO2 estimate for consumer devices in grams on first visit
+ * @property {number} 'consumerDeviceCO2 - subsequent' - The CO2 estimate for consumer devices in grams on subsequent visits
+ * @property {number} 'productionCO2 - first' - The CO2 estimate for device production in grams on first visit
+ * @property {number} 'productionCO2 - subsequent' - The CO2 estimate for device production in grams on subsequent visits
+ * @property {number} total - The total CO2 estimate in grams
+ */
+
 import OneByte from "./1byte.js";
 import SustainableWebDesign from "./sustainable-web-design.js";
 
@@ -70,7 +92,7 @@ class CO2 {
    *
    * @param {number} bytes
    * @param {boolean} green
-   * @return {number} the amount of CO2 in grammes
+   * @return {number|CO2EstimateComponentsPerByte} the amount of CO2 in grammes or its separate components
    */
   perByte(bytes, green = false) {
     return this.model.perByte(bytes, green, this._segment);
@@ -83,7 +105,7 @@ class CO2 {
    *
    * @param {number} bytes
    * @param {boolean} green
-   * @return {number} the amount of CO2 in grammes
+   * @return {number|CO2EstimateComponentsPerVisit} the amount of CO2 in grammes or its separate components
    */
   perVisit(bytes, green = false) {
     if (this.model?.perVisit) {