refactor: add docstrings

Author: rickstaa

src/calculateRank.js

@@ -4,9 +4,9 @@
  *
  * @see https://stackoverflow.com/a/5263759/10629172
  *
- * @param {string} mean
- * @param {number} sigma
- * @param {number} to
+ * @param {string} mean The mean of the normal distribution.
+ * @param {number} sigma The standard deviation of the normal distribution.
+ * @param {number} to The value to calculate the probability for.
  * @returns {number} Probability.
  */
 function normalcdf(mean, sigma, to) {
@@ -29,13 +29,13 @@ function normalcdf(mean, sigma, to) {
 /**
  * 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
+ * @param {number} totalRepos Total number of repos.
+ * @param {number} totalCommits Total number of commits.
+ * @param {number} contributions The number of contributions.
+ * @param {number} followers The number of followers.
+ * @param {number} prs The number of pull requests.
+ * @param {number} issues The number of issues.
+ * @param {number} stargazers The number of stars.
  * @returns {{level: string, score: number}}} The users rank.
  */
 function calculateRank({

src/cards/repo-card.js

@@ -14,11 +14,11 @@ import {
 import { repoCardLocales } from "../translations.js";
 
 /**
- * Retrieves a badge to display the type of repo like template, archived, etc
+ * Retrieves the repository description and wraps it to fit the card width.
  *
- * @param {string} label
- * @param {string} textColor
- * @returns {string} svg badge
+ * @param {string} label The repository description.
+ * @param {string} textColor The color of the text.
+ * @returns {string} Wrapped repo description SVG object.
  */
 const getBadgeSVG = (label, textColor) => `
   <g data-testid="badge" class="badge" transform="translate(320, -18)">
@@ -36,11 +36,11 @@ const getBadgeSVG = (label, textColor) => `
 `;
 
 /**
- * Creates a node to display the primary programming language of the repository
+ * Creates a node to display the primary programming language of the repository.
  *
- * @param {string} langName
- * @param {string} langColor
- * @returns {string} language node
+ * @param {string} langName Language name.
+ * @param {string} langColor Language color.
+ * @returns {string} Language display SVG object.
  */
 const createLanguageNode = (langName, langColor) => {
   return `
@@ -56,10 +56,10 @@ const ICON_SIZE = 16;
 /**
  * Creates an icon with label to display repository stats like forks, stars, etc.
  *
- * @param {string} icon
- * @param {number|string} label
- * @param {string} testid
- * @returns {string} icon with label
+ * @param {string} icon The icon to display.
+ * @param {number|string} label The label to display.
+ * @param {string} testid The testid to assign to the label.
+ * @returns {string} Icon with label SVG object.
  */
 const iconWithLabel = (icon, label, testid) => {
   if (label <= 0) return "";
@@ -80,11 +80,11 @@ const iconWithLabel = (icon, label, testid) => {
 };
 
 /**
- * Renders repository card details
+ * Renders repository card details.
  *
- * @param {import('../fetchers/types').RepositoryData} repo
- * @param {Partial<import("./types").RepoCardOptions>} options
- * @returns {string} repository card
+ * @param {import('../fetchers/types').RepositoryData} repo Repository data.
+ * @param {Partial<import("./types").RepoCardOptions>} options Card options.
+ * @returns {string} Repository card SVG object.
  */
 const renderRepoCard = (repo, options = {}) => {
   const {

src/cards/stats-card.js

@@ -63,9 +63,11 @@ const createTextNode = ({
 };
 
 /**
- * @param {Partial<import('../fetchers/types').StatsData>} stats
- * @param {Partial<import("./types").StatCardOptions>} options
- * @returns {string}
+ * Renders the stats card.
+ * 
+ * @param {Partial<import('../fetchers/types').StatsData>} stats The stats data.
+ * @param {Partial<import("./types").StatCardOptions>} options The card options.
+ * @returns {string} The stats card SVG object.
  */
 const renderStatsCard = (stats = {}, options = { hide: [] }) => {
   const {

src/cards/top-languages-card.js

@@ -23,10 +23,10 @@ const CARD_PADDING = 25;
  */
 
 /**
- * Retrieves the programming language whose name is the longest
+ * Retrieves the programming language whose name is the longest.
  *
- * @param {Lang[]} arr
- * @returns {Object} longest lang obj
+ * @param {Lang[]} arr Array of programming languages.
+ * @returns {Object} Longest programming language object.
  */
 const getLongestLang = (arr) =>
   arr.reduce(
@@ -37,15 +37,14 @@ const getLongestLang = (arr) =>
 
 /**
  * Creates a node to display usage of a programming language in percentage
- * using text and a horizontal progress bar
+ * using text and a horizontal progress bar.
  *
- * @param {{
- *  width: number,
- *  color: string,
- *  name: string,
- *  progress: string
- * }} props
- * @returns {string} progress text node
+ * @param {object[]} props Function properties.
+ * @param {number} props.width The card width
+ * @param {string} props.name Name of the programming language.
+ * @param {string} props.color Color of the programming language.
+ * @param {string} props.progress Usage of the programming language in percentage.
+ * @returns {string} Programming language SVG node.
  */
 const createProgressTextNode = ({ width, color, name, progress }) => {
   const paddingRight = 95;
@@ -67,10 +66,12 @@ const createProgressTextNode = ({ width, color, name, progress }) => {
 };
 
 /**
- * Creates a text only node to display usage of a programming language in percentage
+ * Creates a text only node to display usage of a programming language in percentage.
  *
- * @param {{ lang: Lang, totalSize: number }} props
- * @returns {string} text node
+ * @param {object[]} props Function properties.
+ * @param {Lang} props.lang Programming language object.
+ * @param {number} props.totalSize Total size of all languages.
+ * @returns {string} Compact layout programming language SVG node.
  */
 const createCompactLangNode = ({ lang, totalSize }) => {
   const percentage = ((lang.size / totalSize) * 100).toFixed(2);
@@ -87,10 +88,12 @@ const createCompactLangNode = ({ lang, totalSize }) => {
 };
 
 /**
- * Creates compact layout of text only language nodes
+ * Creates compact layout of text only language nodes.
  *
- * @param {{ langs: Lang[], totalSize: number }} props
- * @returns {string} text nodes layout
+ * @param {object[]} props Function properties.
+ * @param {Lang[]} props.langs Array of programming languages.
+ * @param {number} props.totalSize Total size of all languages.
+ * @returns {string} Programming languages SVG node.
  */
 const createLanguageTextNode = ({ langs, totalSize }) => {
   const longestLang = getLongestLang(langs);
@@ -122,12 +125,12 @@ const createLanguageTextNode = ({ langs, totalSize }) => {
 };
 
 /**
- * Renders layout to display user's most frequently used programming languages
+ * Renders layout to display user's most frequently used programming languages.
  *
- * @param {Lang[]} langs
- * @param {number} width
- * @param {number} totalLanguageSize
- * @returns {string} normal layout
+ * @param {Lang[]} langs Array of programming languages.
+ * @param {number} width Card width.
+ * @param {number} totalLanguageSize Total size of all languages.
+ * @returns {string} Normal layout card SVG object.
  */
 const renderNormalLayout = (langs, width, totalLanguageSize) => {
   return flexLayout({
@@ -145,12 +148,12 @@ const renderNormalLayout = (langs, width, totalLanguageSize) => {
 };
 
 /**
- * Renders compact layout to display user's most frequently used programming languages
+ * Renders compact layout to display user's most frequently used programming languages.
  *
- * @param {Lang[]} langs
- * @param {number} width
- * @param {number} totalLanguageSize
- * @returns {string} compact layout
+ * @param {Lang[]} langs Array of programming languages.
+ * @param {number} width Card width.
+ * @param {number} totalLanguageSize Total size of all languages.
+ * @returns {string} Compact layout card SVG object.
  */
 const renderCompactLayout = (langs, width, totalLanguageSize) => {
   const paddingRight = 50;
@@ -198,30 +201,31 @@ const renderCompactLayout = (langs, width, totalLanguageSize) => {
 };
 
 /**
- * Calculates height for the compact layout
+ * Calculates height for the compact layout.
  *
- * @param {number} totalLangs
- * @returns {number} height
+ * @param {number} totalLangs Total number of languages.
+ * @returns {number} Card height.
  */
 const calculateCompactLayoutHeight = (totalLangs) => {
   return 90 + Math.round(totalLangs / 2) * 25;
 };
 
 /**
- * Calculates height for the normal layout
+ * Calculates height for the normal layout.
  *
- * @param {number} totalLangs
- * @returns {number} height
+ * @param {number} totalLangs Total number of languages.
+ * @returns {number} Card height.
  */
 const calculateNormalLayoutHeight = (totalLangs) => {
   return 45 + (totalLangs + 1) * 40;
 };
 
 /**
- *
- * @param {Record<string, Lang>} topLangs
- * @param {string[]} hide
- * @param {string} langs_count
+ *  Hides languages and trims the list to show only the top N languages.
+ * 
+ * @param {Record<string, Lang>} topLangs Top languages.
+ * @param {string[]} hide Languages to hide.
+ * @param {string} langs_count Number of languages to show.
  */
 const useLanguages = (topLangs, hide, langs_count) => {
   let langs = Object.values(topLangs);
@@ -250,11 +254,11 @@ const useLanguages = (topLangs, hide, langs_count) => {
 };
 
 /**
- * Renders card to display user's most frequently used programming languages
+ * Renders card to display user's most frequently used programming languages.
  *
- * @param {import('../fetchers/types').TopLangData} topLangs
- * @param {Partial<import("./types").TopLangOptions>} options
- * @returns {string}
+ * @param {import('../fetchers/types').TopLangData} topLangs User's most frequently used programming languages.
+ * @param {Partial<import("./types").TopLangOptions>} options Card options.
+ * @returns {string} Language card SVG object.
  */
 const renderTopLanguages = (topLangs, options = {}) => {
   const {

src/cards/wakatime-card.js

@@ -23,7 +23,9 @@ const require = createRequire(import.meta.url);
 const languageColors = require("../common/languageColors.json"); // now works
 
 /**
- * @param {{color: string, text: string}} param0
+ * Creates the no coding activity SVG node.
+ * 
+ * @param {{color: string, text: string}} The function prop
  */
 const noCodingActivityNode = ({ color, text }) => {
   return `
@@ -32,13 +34,13 @@ const noCodingActivityNode = ({ color, text }) => {
 };
 
 /**
- *
- * @param {{
- *  lang: import("../fetchers/types").WakaTimeLang,
- *  totalSize: number,
- *  x: number,
- *  y: number
- * }} props
+ * Create compact WakaTime layout.
+ * 
+ * @param {Object[]} args The function arguments.
+ * @param {import("../fetchers/types").WakaTimeLang[]} languages The languages array.
+ * @param {number} totalSize The total size of the languages.
+ * @param {number} x The x position of the language node.
+ * @param {number} y The y position of the language node.
  */
 const createCompactLangNode = ({ lang, totalSize, x, y }) => {
   const color = languageColors[lang.name] || "#858585";
@@ -54,12 +56,13 @@ const createCompactLangNode = ({ lang, totalSize, x, y }) => {
 };
 
 /**
- * @param {{
- *  langs: import("../fetchers/types").WakaTimeLang[],
- *  totalSize: number,
- *  x: number,
- *  y: number
- * }} props
+ * Create WakaTime language text node item.
+ * 
+ * @param {Object[]} args The function arguments.
+ * @param {import("../fetchers/types").WakaTimeLang} lang The language object.
+ * @param {number} totalSize The total size of the languages.
+ * @param {number} x The x position of the language node.
+ * @param {number} y The y position of the language node.
  */
 const createLanguageTextNode = ({ langs, totalSize, x, y }) => {
   return langs.map((lang, index) => {
@@ -81,17 +84,16 @@ const createLanguageTextNode = ({ langs, totalSize, x, y }) => {
 };
 
 /**
- *
- * @param {{
- *  id: string;
- *  label: string;
- *  value: string;
- *  index: number;
- *  percent: number;
- *  hideProgress: boolean;
- *  progressBarColor: string;
- *  progressBarBackgroundColor: string
- * }} props
+ * Create WakaTime text item.
+ * 
+ * @param {Object[]} args The function arguments.
+ * @param {string} id The id of the text node item.
+ * @param {string} label The label of the text node item.
+ * @param {string} value The value of the text node item.
+ * @param {number} index The index of the text node item.
+ * @param {percent} percent Percentage of the text node item.
+ * @param {boolean} hideProgress Whether to hide the progress bar.
+ * @param {string} progressBarBackgroundColor The color of the progress bar background.
  */
 const createTextNode = ({
   id,
@@ -132,11 +134,13 @@ const createTextNode = ({
 };
 
 /**
- * @param {import("../fetchers/types").WakaTimeLang[]} languages
+ * Recalculating percentages so that, compact layout's progress bar does not break when 
+ * hiding languages.
+ * 
+ * @param {import("../fetchers/types").WakaTimeLang[]} languages The languages array.
+ * @return {import("../fetchers/types").WakaTimeLang[]} The recalculated languages array.
  */
 const recalculatePercentages = (languages) => {
-  // recalculating percentages so that,
-  // compact layout's progress bar does not break when hiding languages
   const totalSum = languages.reduce(
     (totalSum, language) => totalSum + language.percent,
     0,
@@ -148,9 +152,11 @@ const recalculatePercentages = (languages) => {
 };
 
 /**
- * @param {Partial<import('../fetchers/types').WakaTimeData>} stats
- * @param {Partial<import('./types').WakaTimeOptions>} options
- * @returns {string}
+ * Renders WakaTime card.
+ * 
+ * @param {Partial<import('../fetchers/types').WakaTimeData>} stats WakaTime stats.
+ * @param {Partial<import('./types').WakaTimeOptions>} options Card options.
+ * @returns {string} WakaTime card SVG.
  */
 const renderWakatimeCard = (stats = {}, options = { hide: [] }) => {
   let { languages } = stats;