fix: adding docstrings to the files where it was missing (#2101)

* fix: adding docstrings to missing files

* style: format code

* style: improve formatting

Co-authored-by: Jagruti Tiwari <jagrutit@cdac.in>
Co-authored-by: rickstaa <rick.staa@outlook.com>

src/calculateRank.js

@@ -1,4 +1,14 @@
-// https://stackoverflow.com/a/5263759/10629172
+/**
+ * Calculates the probability of x taking on x or a value less than x in a normal distribution
+ * with mean and standard deviation.
+ *
+ * @see https://stackoverflow.com/a/5263759/10629172
+ *
+ * @param {string} mean
+ * @param {number} sigma
+ * @param {number} to
+ * @returns {number} Probability.
+ */
 function normalcdf(mean, sigma, to) {
   var z = (to - mean) / Math.sqrt(2 * sigma * sigma);
   var t = 1 / (1 + 0.3275911 * Math.abs(z));
@@ -16,6 +26,18 @@ function normalcdf(mean, sigma, to) {
   return (1 / 2) * (1 + sign * erf);
 }
 
+/**
+ * Calculates the users rank.
+ *
+ * @param {number} totalRepos
+ * @param {number} totalCommits
+ * @param {number} contributions
+ * @param {number} followers
+ * @param {number} prs
+ * @param {number} issues
+ * @param {number} stargazers
+ * @returns {{level: string, score: number}}} The users rank.
+ */
 function calculateRank({
   totalRepos,
   totalCommits,

src/cards/stats-card.js

@@ -12,6 +12,19 @@ import {
 import { getStyles } from "../getStyles.js";
 import { statCardLocales } from "../translations.js";
 
+/**
+ * Create a stats card text item.
+ *
+ * @param {object[]} createTextNodeParams Object that contains the createTextNode parameters.
+ * @param {string} createTextNodeParams.label The label to display.
+ * @param {string} createTextNodeParams.value The value to display.
+ * @param {string} createTextNodeParams.id The id of the stat.
+ * @param {number} createTextNodeParams.index The index of the stat.
+ * @param {boolean} createTextNodeParams.showIcons Whether to show icons.
+ * @param {number} createTextNodeParams.shiftValuePos Number of pixels the value has to be shifted to the right.
+ * @param {boolean} createTextNodeParams.bold Whether to bold the label.
+ * @returns
+ */
 const createTextNode = ({
   icon,
   label,

src/common/retryer.js

@@ -1,5 +1,14 @@
 import { CustomError, logger } from "./utils.js";
 
+/**
+ * Try to execute the fetcher function until it succeeds or the max number of retries is reached.
+ *
+ * @param {object[]} retryerParams Object that contains the createTextNode parameters.
+ * @param {object[]} retryerParams.fetcher The fetcher function.
+ * @param {object[]} retryerParams.variables Object with arguments to pass to the fetcher function.
+ * @param {number} retryerParams.retries How many times to retry.
+ * @returns Promise<retryer>
+ */
 const retryer = async (fetcher, variables, retries = 0) => {
   if (retries > 7) {
     throw new CustomError("Maximum retries exceeded", CustomError.MAX_RETRY);

src/common/utils.js

@@ -74,7 +74,10 @@ function parseBoolean(value) {
 }
 
 /**
- * @param {string} str
+ * Parse string to array of strings.
+ *
+ * @param {string} str The string to parse.
+ * @returns {string[]} The array of strings.
  */
 function parseArray(str) {
   if (!str) return [];
@@ -82,9 +85,12 @@ function parseArray(str) {
 }
 
 /**
- * @param {number} number
- * @param {number} min
- * @param {number} max
+ * Clamp the given number between the given range.
+ *
+ * @param {number} number The number to clamp.
+ * @param {number} min The minimum value.
+ * @param {number} max The maximum value.
+ * returns {number} The clamped number.
  */
 function clampValue(number, min, max) {
   // @ts-ignore
@@ -93,7 +99,10 @@ function clampValue(number, min, max) {
 }
 
 /**
- * @param {string[]} colors
+ * Check if the given string is a valid gradient.
+ *
+ * @param {string[]} colors Array of colors.
+ * returns {boolean} True if the given string is a valid gradient.
  */
 function isValidGradient(colors) {
   return isValidHexColor(colors[1]) && isValidHexColor(colors[2]);