From 708dfb5f5fa95b7e865eb545228942f5394103ea Mon Sep 17 00:00:00 2001
From: Prashant Rawat <pr7prashant@gmail.com>
Date: Wed, 25 May 2022 00:50:02 +0530
Subject: [PATCH] Add docstrings for color formatter service (#8000)

* add docstrings for color formatter service

* add module description for build status service

Co-authored-by: repo-ranger[bot] <39074581+repo-ranger[bot]@users.noreply.github.com>
---
 services/build-status.js     |  2 ++
 services/color-formatters.js | 70 ++++++++++++++++++++++++++++++++++++
 2 files changed, 72 insertions(+)

diff --git a/services/build-status.js b/services/build-status.js
index 20b40cd54b..77a6da0f59 100644
--- a/services/build-status.js
+++ b/services/build-status.js
@@ -1,4 +1,6 @@
 /**
+ * Common functions and schemas for tasks related to build status.
+ *
  * @module
  */
 
diff --git a/services/color-formatters.js b/services/color-formatters.js
index a79e83c016..518a2a51f5 100644
--- a/services/color-formatters.js
+++ b/services/color-formatters.js
@@ -1,10 +1,19 @@
 /**
  * Commonly-used functions for determining the colour to use for a badge,
  * including colours based off download count, version number, etc.
+ *
+ * @module
  */
+
 import moment from 'moment'
 import pep440 from '@renovate/pep440'
 
+/**
+ * Determines the color used for a badge based on version.
+ *
+ * @param {string|number} version Version used for determining badge color
+ * @returns {string} Badge color
+ */
 function version(version) {
   if (typeof version !== 'string' && typeof version !== 'number') {
     throw new Error(`Can't generate a version color for ${version}`)
@@ -21,6 +30,12 @@ function version(version) {
   }
 }
 
+/**
+ * Determines the color used for a badge based on PEP440 versioning.
+ *
+ * @param {string|number} version Version used for determining badge color
+ * @returns {string} Badge color
+ */
 function pep440VersionColor(version) {
   if (!pep440.valid(version)) {
     return 'lightgrey'
@@ -32,6 +47,18 @@ function pep440VersionColor(version) {
   return 'blue'
 }
 
+/**
+ * Determines the color used for a badge by comparing the value and floor count values.
+ * The color can vary from red to bright green depending on the range the value lies in.
+ * Decreasing the value will shift the color towards red.
+ * Increasing the value will shift the color towards bright green.
+ *
+ * @param {number} value Current value
+ * @param {number} yellow Yellow color threshold, should be greater than 0
+ * @param {number} yellowgreen Yellowgreen color threshold, should be greater than yellow
+ * @param {number} green Green color threshold, should be greater than yellowgreen
+ * @returns {string} Badge color
+ */
 function floorCount(value, yellow, yellowgreen, green) {
   if (value <= 0) {
     return 'red'
@@ -46,14 +73,37 @@ function floorCount(value, yellow, yellowgreen, green) {
   }
 }
 
+/**
+ * Determines the color used for a badge by comparing the download count and floor values.
+ * The color varies from red to bright green as the download count increases.
+ *
+ * @param {number} downloads Download count
+ * @returns {string} Badge color
+ */
 function downloadCount(downloads) {
   return floorCount(downloads, 10, 100, 1000)
 }
 
+/**
+ * Determines the color used for a badge by comparing percentage and floor values.
+ * The color varies from red to bright green as the percentage increases.
+ *
+ * @param {number} percentage Percentage value
+ * @returns {string} Badge color
+ */
 function coveragePercentage(percentage) {
   return floorCount(percentage, 80, 90, 100)
 }
 
+/**
+ * Determines the color used for a badge by matching score with grade values.
+ * The color varies from bright green to red as the score decreases.
+ * The score can be one of the following grade value: ['A', 'B', 'C', 'D', 'E'].
+ * The color defaults to red if the score does not matches with any of the grade values.
+ *
+ * @param {string} score Score value
+ * @returns {string} Badge color
+ */
 function letterScore(score) {
   if (score === 'A') {
     return 'brightgreen'
@@ -70,6 +120,18 @@ function letterScore(score) {
   }
 }
 
+/**
+ * Creates a callback function that determines badge color from the colors array.
+ * If the colors array is provided then for n steps, there should be n + 1 color.
+ * If the colors array is not provided then it is chosen from the default colors array
+ * according to the size of the steps array.
+ *
+ * @param {number[]} steps Steps array
+ * @param {string[]} colors Colors array. If provided, should be of length steps.length + 1
+ * @param {boolean} reversed If true then the colors array will be considered in reverse order
+ * @returns {function(number): string} Function that finds the step index by comparing value
+ * with steps array and returns color from colors array for the corresponding step index
+ */
 function colorScale(steps, colors, reversed) {
   if (steps === undefined) {
     throw Error('When invoking colorScale, steps should be provided.')
@@ -110,6 +172,14 @@ function colorScale(steps, colors, reversed) {
   }
 }
 
+/**
+ * Determines the color used for a badge according to the age.
+ * Age is calculated as days elapsed till current date.
+ * The color varies from bright green to red as the age increases.
+ *
+ * @param {string} date Date string
+ * @returns {string} Badge color
+ */
 function age(date) {
   const colorByAge = colorScale([7, 30, 180, 365, 730], undefined, true)
   const daysElapsed = moment().diff(moment(date), 'days')