thegreenwebfoundation / developer-docs

The developer documentation site for The Green Web Foundations open source libraries.
https://developers.thegreenwebfoundation.org
Apache License 2.0
5 stars 13 forks source link

Add more args to `perVisit` docs #28

Closed drydenwilliams closed 1 year ago

drydenwilliams commented 1 year ago

Is your feature request related to a problem? Please describe. I thought I wanted to use perVisit to pass in carbon intensity. But couldn't see this as an option in the documentation. So had to check out the code to see if I could pass it in options

Describe the solution you'd like Just a few more options on the documentation as per the code

  perVisit(
    bytes,
    carbonIntensity = false,
    segmentResults = false,
    options = {}
  ) {
fershad commented 1 year ago

Since this issue is related to the docs website, I've moved it into that repo (out of the CO2.js repo)

fershad commented 1 year ago

@drydenwilliams we'd like folks who want to use options to change some of the inputs of the function to use the perVisitTrace function. The reason for this is that if a calculation is going to steer off the baseline SWD model, then we believe they should make it clear what changes have been made. In this way there's a transparency to the calculation.

Action: I will add this guidance to the docs.

The reason the underlying perVisit function (https://github.com/thegreenwebfoundation/co2.js/blob/9ed607d752bf7fd4eb3b255350aadf302bbb69a8/src/sustainable-web-design.js#L165-L170) takes an object variable was to avoid having to duplicate the code for perVisit and perVisitTrace. This could be fixed up by refactoring the code, which is something that will probably happen alongside the SWD model update later this year.

fershad commented 1 year ago

I've included guidance that the perByteTrace and perVisitTrace functions should be used whenever the variables in the SWD model want to be adjusted. https://developers.thegreenwebfoundation.org/co2js/methods/