diff --git a/src/calculateRank.js b/src/calculateRank.js index 6c161f3..85d9658 100644 --- a/src/calculateRank.js +++ b/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({ diff --git a/src/cards/repo-card.js b/src/cards/repo-card.js index 5730ea4..a306c1d 100644 --- a/src/cards/repo-card.js +++ b/src/cards/repo-card.js @@ -14,9 +14,11 @@ import { import { repoCardLocales } from "../translations.js"; /** - * @param {string} label - * @param {string} textColor - * @returns {string} + * Retrieves the repository description and wraps it to fit the card width. + * + * @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) => ` @@ -34,9 +36,11 @@ const getBadgeSVG = (label, textColor) => ` `; /** - * @param {string} langName - * @param {string} langColor - * @returns {string} + * Creates a node to display the primary programming language of the repository. + * + * @param {string} langName Language name. + * @param {string} langColor Language color. + * @returns {string} Language display SVG object. */ const createLanguageNode = (langName, langColor) => { return ` @@ -48,6 +52,15 @@ const createLanguageNode = (langName, langColor) => { }; const ICON_SIZE = 16; + +/** + * Creates an icon with label to display repository stats like forks, stars, etc. + * + * @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 ""; const iconSvg = ` @@ -67,9 +80,11 @@ const iconWithLabel = (icon, label, testid) => { }; /** - * @param {import('../fetchers/types').RepositoryData} repo - * @param {Partial} options - * @returns {string} + * Renders repository card details. + * + * @param {import('../fetchers/types').RepositoryData} repo Repository data. + * @param {Partial} options Card options. + * @returns {string} Repository card SVG object. */ const renderRepoCard = (repo, options = {}) => { const { diff --git a/src/cards/stats-card.js b/src/cards/stats-card.js index f880560..c9ab66e 100644 --- a/src/cards/stats-card.js +++ b/src/cards/stats-card.js @@ -63,9 +63,11 @@ const createTextNode = ({ }; /** - * @param {Partial} stats - * @param {Partial} options - * @returns {string} + * Renders the stats card. + * + * @param {Partial} stats The stats data. + * @param {Partial} options The card options. + * @returns {string} The stats card SVG object. */ const renderStatsCard = (stats = {}, options = { hide: [] }) => { const { diff --git a/src/cards/top-languages-card.js b/src/cards/top-languages-card.js index b837b35..602d1b8 100644 --- a/src/cards/top-languages-card.js +++ b/src/cards/top-languages-card.js @@ -23,7 +23,10 @@ const CARD_PADDING = 25; */ /** - * @param {Lang[]} arr + * Retrieves the programming language whose name is the longest. + * + * @param {Lang[]} arr Array of programming languages. + * @returns {Object} Longest programming language object. */ const getLongestLang = (arr) => arr.reduce( @@ -33,12 +36,15 @@ const getLongestLang = (arr) => ); /** - * @param {{ - * width: number, - * color: string, - * name: string, - * progress: string - * }} props + * Creates a node to display usage of a programming language in percentage + * using text and a horizontal progress bar. + * + * @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; @@ -60,7 +66,12 @@ const createProgressTextNode = ({ width, color, name, progress }) => { }; /** - * @param {{ lang: Lang, totalSize: number }} props + * Creates a text only node to display usage of a programming language in percentage. + * + * @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); @@ -77,7 +88,12 @@ const createCompactLangNode = ({ lang, totalSize }) => { }; /** - * @param {{ langs: Lang[], totalSize: number }} props + * Creates compact layout of text only language nodes. + * + * @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); @@ -109,10 +125,12 @@ const createLanguageTextNode = ({ langs, totalSize }) => { }; /** - * @param {Lang[]} langs - * @param {number} width - * @param {number} totalLanguageSize - * @returns {string} + * Renders layout to display user's most frequently used programming languages. + * + * @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({ @@ -130,10 +148,12 @@ const renderNormalLayout = (langs, width, totalLanguageSize) => { }; /** - * @param {Lang[]} langs - * @param {number} width - * @param {number} totalLanguageSize - * @returns {string} + * Renders compact layout to display user's most frequently used programming languages. + * + * @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; @@ -181,26 +201,31 @@ const renderCompactLayout = (langs, width, totalLanguageSize) => { }; /** - * @param {number} totalLangs - * @returns {number} + * Calculates height for the compact layout. + * + * @param {number} totalLangs Total number of languages. + * @returns {number} Card height. */ const calculateCompactLayoutHeight = (totalLangs) => { return 90 + Math.round(totalLangs / 2) * 25; }; /** - * @param {number} totalLangs - * @returns {number} + * Calculates height for the normal layout. + * + * @param {number} totalLangs Total number of languages. + * @returns {number} Card height. */ const calculateNormalLayoutHeight = (totalLangs) => { return 45 + (totalLangs + 1) * 40; }; /** + * Hides languages and trims the list to show only the top N languages. * - * @param {Record} topLangs - * @param {string[]} hide - * @param {string} langs_count + * @param {Record} 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); @@ -229,9 +254,11 @@ const useLanguages = (topLangs, hide, langs_count) => { }; /** - * @param {import('../fetchers/types').TopLangData} topLangs - * @param {Partial} options - * @returns {string} + * Renders card to display user's most frequently used programming languages. + * + * @param {import('../fetchers/types').TopLangData} topLangs User's most frequently used programming languages. + * @param {Partial} options Card options. + * @returns {string} Language card SVG object. */ const renderTopLanguages = (topLangs, options = {}) => { const { diff --git a/src/cards/wakatime-card.js b/src/cards/wakatime-card.js index 24571e7..8b042fd 100644 --- a/src/cards/wakatime-card.js +++ b/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 }) => { }; /** + * Create compact WakaTime layout. * - * @param {{ - * lang: import("../fetchers/types").WakaTimeLang, - * totalSize: number, - * x: number, - * y: number - * }} props + * @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 }) => { }; /** + * Create WakaTime text item. * - * @param {{ - * id: string; - * label: string; - * value: string; - * index: number; - * percent: number; - * hideProgress: boolean; - * progressBarColor: string; - * progressBarBackgroundColor: string - * }} props + * @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} stats - * @param {Partial} options - * @returns {string} + * Renders WakaTime card. + * + * @param {Partial} stats WakaTime stats. + * @param {Partial} options Card options. + * @returns {string} WakaTime card SVG. */ const renderWakatimeCard = (stats = {}, options = { hide: [] }) => { let { languages } = stats; diff --git a/src/common/Card.js b/src/common/Card.js index 5fd4b9f..2f1d9c2 100644 --- a/src/common/Card.js +++ b/src/common/Card.js @@ -3,14 +3,16 @@ import { encodeHTML, flexLayout } from "./utils.js"; class Card { /** - * @param {object} args - * @param {number?=} args.width - * @param {number?=} args.height - * @param {number?=} args.border_radius - * @param {string?=} args.customTitle - * @param {string?=} args.defaultTitle - * @param {string?=} args.titlePrefixIcon - * @param {ReturnType?=} args.colors + * Creates a new card instance. + * + * @param {object} args Card arguments. + * @param {number?=} args.width Card width. + * @param {number?=} args.height Card height. + * @param {number?=} args.border_radius Card border radius. + * @param {string?=} args.customTitle Card custom title. + * @param {string?=} args.defaultTitle Card default title. + * @param {string?=} args.titlePrefixIcon Card title prefix icon. + * @returns {Card} Card instance. */ constructor({ width = 100, diff --git a/src/common/I18n.js b/src/common/I18n.js index 7f607cd..48242af 100644 --- a/src/common/I18n.js +++ b/src/common/I18n.js @@ -1,3 +1,6 @@ +/** + * I18n translation class. + */ class I18n { constructor({ locale, translations }) { this.locale = locale; diff --git a/src/common/createProgressNode.js b/src/common/createProgressNode.js index 4cc3747..c36818b 100644 --- a/src/common/createProgressNode.js +++ b/src/common/createProgressNode.js @@ -1,5 +1,17 @@ import { clampValue } from "./utils.js"; +/** + * Create a node to indicate progress in percentage along a horizontal line. + * + * @param {Object} createProgressNodeParams Object that contains the createProgressNode parameters. + * @param {number} createProgressNodeParams.x X-axis position. + * @param {number} createProgressNodeParams.y Y-axis position. + * @param {number} createProgressNodeParams.width Width of progress bar. + * @param {string} createProgressNodeParams.color Progress color. + * @param {string} createProgressNodeParams.progress Progress value. + * @param {string} createProgressNodeParams.progressBarBackgroundColor Progress bar bg color. + * @returns {string} Progress node. + */ const createProgressNode = ({ x, y, diff --git a/src/common/utils.js b/src/common/utils.js index fc462d3..b41ed0c 100644 --- a/src/common/utils.js +++ b/src/common/utils.js @@ -5,9 +5,11 @@ import wrap from "word-wrap"; import { themes } from "../../themes/index.js"; /** - * @param {string} message - * @param {string} secondaryMessage - * @returns {string} + * Renders error message on the card. + * + * @param {string} message Main error message. + * @param {string} secondaryMessage The secondary error message. + * @returns {string} The SVG markup. */ const renderError = (message, secondaryMessage = "") => { return ` @@ -28,9 +30,12 @@ const renderError = (message, secondaryMessage = "") => { }; /** + * Encode string as HTML. + * * @see https://stackoverflow.com/a/48073476/10629172 - * @param {string} str - * @returns {string} + * + * @param {string} str String to encode. + * @returns {string} Encoded string. */ function encodeHTML(str) { return str @@ -41,7 +46,10 @@ function encodeHTML(str) { } /** - * @param {number} num + * Retrieves num with suffix k(thousands) precise to 1 decimal if greater than 999. + * + * @param {number} num The number to format. + * @returns {string|number} The formatted number. */ function kFormatter(num) { return Math.abs(num) > 999 @@ -50,8 +58,10 @@ function kFormatter(num) { } /** - * @param {string} hexColor - * @returns {boolean} + * Checks if a string is a valid hex color. + * + * @param {string} hexColor String to check. + * @returns {boolean} True if the given string is a valid hex color. */ function isValidHexColor(hexColor) { return new RegExp( @@ -60,8 +70,10 @@ function isValidHexColor(hexColor) { } /** - * @param {string} value - * @returns {boolean | string} + * Returns boolean if value is either "true" or "false" else the value as it is. + * + * @param {string} value The value to parse. + * @returns {boolean | string} The parsed value. */ function parseBoolean(value) { if (value === "true") { @@ -102,16 +114,18 @@ function clampValue(number, min, max) { * 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. + * @returns {boolean} True if the given string is a valid gradient. */ function isValidGradient(colors) { return isValidHexColor(colors[1]) && isValidHexColor(colors[2]); } /** - * @param {string} color - * @param {string} fallbackColor - * @returns {string | string[]} + * Retrieves a gradient if color has more than one valid hex codes else a single color. + * + * @param {string} color The color to parse. + * @param {string} fallbackColor The fallback color. + * @returns {string | string[]} The gradient or color. */ function fallbackColor(color, fallbackColor) { let colors = color.split(","); @@ -128,8 +142,11 @@ function fallbackColor(color, fallbackColor) { } /** - * @param {import('axios').AxiosRequestConfig['data']} data - * @param {import('axios').AxiosRequestConfig['headers']} headers + * Send GraphQL request to GitHub API. + * + * @param {import('axios').AxiosRequestConfig['data']} data Request data. + * @param {import('axios').AxiosRequestConfig['headers']} headers Request headers. + * @returns {Promise} Request response. */ function request(data, headers) { // @ts-ignore @@ -142,17 +159,15 @@ function request(data, headers) { } /** - * @param {object} props - * @param {string[]} props.items - * @param {number} props.gap - * @param {number[]?=} props.sizes - * @param {"column" | "row"?=} props.direction + * Auto layout utility, allows us to layout things vertically or horizontally with + * proper gaping. * - * @returns {string[]} - * - * @description - * Auto layout utility, allows us to layout things - * vertically or horizontally with proper gaping + * @param {object} props Function properties. + * @param {string[]} props.items Array of items to layout. + * @param {number} props.gap Gap between items. + * @param {number[]?=} props.sizes Array of sizes for each item. + * @param {"column" | "row"?=} props.direction Direction to layout items. + * @returns {string[]} Array of items with proper layout. */ function flexLayout({ items, gap, direction, sizes = [] }) { let lastSize = 0; @@ -169,18 +184,17 @@ function flexLayout({ items, gap, direction, sizes = [] }) { } /** - * @typedef {object} CardColors - * @prop {string?=} title_color - * @prop {string?=} text_color - * @prop {string?=} icon_color - * @prop {string?=} bg_color - * @prop {string?=} border_color - * @prop {keyof typeof import('../../themes')?=} fallbackTheme - * @prop {keyof typeof import('../../themes')?=} theme - */ -/** - * returns theme based colors with proper overrides and defaults - * @param {CardColors} options + * Returns theme based colors with proper overrides and defaults. + * + * @param {Object[]} args Function arguments. + * @param {string} args.title_color Card title color. + * @param {string} args.text_color Card text color. + * @param {string} args.icon_color Card icon color. + * @param {string} args.bg_color Card background color. + * @param {string} args.border_color Card border color. + * @param {string} args.theme Card theme. + * @param {string} args.fallbackTheme Fallback theme. + * */ function getCardColors({ title_color, @@ -224,10 +238,12 @@ function getCardColors({ } /** - * @param {string} text - * @param {number} width - * @param {number} maxLines - * @returns {string[]} + * Split text over multiple lines based on the card width. + * + * @param {string} text Text to split. + * @param {number} width Card width. + * @param {number} maxLines Maximum number of lines. + * @returns {string[]} Array of lines. */ function wrapTextMultiline(text, width = 59, maxLines = 3) { const fullWidthComma = ","; @@ -274,10 +290,13 @@ const SECONDARY_ERROR_MESSAGES = { USER_NOT_FOUND: "Make sure the provided username is not an organization", }; +/** + * Custom error class to handle custom GRS errors. + */ class CustomError extends Error { /** - * @param {string} message - * @param {string} type + * @param {string} message Error message. + * @param {string} type Error type. */ constructor(message, type) { super(message); @@ -289,6 +308,9 @@ class CustomError extends Error { static USER_NOT_FOUND = "USER_NOT_FOUND"; } +/** + * Missing query parameter class. + */ class MissingParamError extends Error { /** * @param {string[]} missedParams @@ -305,10 +327,12 @@ class MissingParamError extends Error { } /** + * Retrieve text length. + * * @see https://stackoverflow.com/a/48172630/10629172 - * @param {string} str - * @param {number} fontSize - * @returns + * @param {string} str String to measure. + * @param {number} fontSize Font size. + * @returns {number} Text length. */ function measureText(str, fontSize = 10) { // prettier-ignore @@ -348,10 +372,12 @@ function measureText(str, fontSize = 10) { const lowercaseTrim = (name) => name.toLowerCase().trim(); /** - * @template T - * @param {Array} arr - * @param {number} perChunk - * @returns {Array} + * Split array of languages in two columns. + * + * @template T Langauge object. + * @param {Array} arr Array of languages. + * @param {number} perChunk Number of languages per column. + * @returns {Array} Array of languages split in two columns. */ function chunkArray(arr, perChunk) { return arr.reduce((resultArray, item, index) => { @@ -368,9 +394,10 @@ function chunkArray(arr, perChunk) { } /** + * Parse emoji from string. * - * @param {string} str - * @returns {string} + * @param {string} str String to parse emoji from. + * @returns {string} String with emoji parsed. */ function parseEmojis(str) { if (!str) throw new Error("[parseEmoji]: str argument not provided"); diff --git a/src/fetchers/repo-fetcher.js b/src/fetchers/repo-fetcher.js index 37bce0e..9ff907c 100644 --- a/src/fetchers/repo-fetcher.js +++ b/src/fetchers/repo-fetcher.js @@ -3,8 +3,11 @@ import { retryer } from "../common/retryer.js"; import { MissingParamError, request } from "../common/utils.js"; /** - * @param {import('Axios').AxiosRequestHeaders} variables - * @param {string} token + * Repo data fetcher. + * + * @param {import('Axios').AxiosRequestHeaders} variables Fetcher variables. + * @param {string} token Github token. + * @returns {Promise} The response. */ const fetcher = (variables, token) => { return request( @@ -51,9 +54,11 @@ const fetcher = (variables, token) => { const urlExample = "/api/pin?username=USERNAME&repo=REPO_NAME"; /** - * @param {string} username - * @param {string} reponame - * @returns {Promise} + * Fetch repository data. + * + * @param {string} username Github username. + * @param {string} reponame Github repository name. + * @returns {Promise} Repository data. */ async function fetchRepo(username, reponame) { if (!username && !reponame) { diff --git a/src/fetchers/stats-fetcher.js b/src/fetchers/stats-fetcher.js index 941c7e1..6a5a6e9 100644 --- a/src/fetchers/stats-fetcher.js +++ b/src/fetchers/stats-fetcher.js @@ -14,8 +14,11 @@ import { dotenv.config(); /** - * @param {import('axios').AxiosRequestHeaders} variables - * @param {string} token + * Stats fetcher object. + * + * @param {import('axios').AxiosRequestHeaders} variables Fetcher variables. + * @param {string} token Github token. + * @returns {Promise} Stats fetcher response. */ const fetcher = (variables, token) => { return request( @@ -59,8 +62,11 @@ const fetcher = (variables, token) => { }; /** - * @param {import('axios').AxiosRequestHeaders} variables - * @param {string} token + * Fetch first 100 repositories for a given username. + * + * @param {import('axios').AxiosRequestHeaders} variables Fetcher variables. + * @param {string} token Github token. + * @returns {Promise} Repositories fetcher response. */ const repositoriesFetcher = (variables, token) => { return request( @@ -91,8 +97,15 @@ const repositoriesFetcher = (variables, token) => { ); }; -// https://github.com/anuraghazra/github-readme-stats/issues/92#issuecomment-661026467 -// https://github.com/anuraghazra/github-readme-stats/pull/211/ +/** + * Fetch all the commits for all the repositories of a given username. + * + * @param {*} username Github username. + * @returns {Promise} Total commits. + * + * @description Done like this because the Github API does not provide a way to fetch all the commits. See + * #92#issuecomment-661026467 and #211 for more information. + */ const totalCommitsFetcher = async (username) => { if (!githubUsernameRegex.test(username)) { logger.log("Invalid username"); @@ -127,9 +140,11 @@ const totalCommitsFetcher = async (username) => { }; /** - * Fetch all the stars for all the repositories of a given username - * @param {string} username - * @param {array} repoToHide + * Fetch all the stars for all the repositories of a given username. + * + * @param {string} username Github username. + * @param {array} repoToHide Repositories to hide. + * @returns {Promise} Total stars. */ const totalStarsFetcher = async (username, repoToHide) => { let nodes = []; @@ -165,10 +180,12 @@ const totalStarsFetcher = async (username, repoToHide) => { }; /** - * @param {string} username - * @param {boolean} count_private - * @param {boolean} include_all_commits - * @returns {Promise} + * Fetch stats for a given username. + * + * @param {string} username Github username. + * @param {boolean} count_private Include private contributions. + * @param {boolean} include_all_commits Include all commits. + * @returns {Promise} Stats data. */ async function fetchStats( username, diff --git a/src/fetchers/top-languages-fetcher.js b/src/fetchers/top-languages-fetcher.js index 181375d..7684213 100644 --- a/src/fetchers/top-languages-fetcher.js +++ b/src/fetchers/top-languages-fetcher.js @@ -6,8 +6,11 @@ import { logger, MissingParamError, request } from "../common/utils.js"; dotenv.config(); /** - * @param {import('Axios').AxiosRequestHeaders} variables - * @param {string} token + * Top languages fetcher object. + * + * @param {import('Axios').AxiosRequestHeaders} variables Fetcher variables. + * @param {string} token Github token. + * @returns {Promise} Languages fetcher response. */ const fetcher = (variables, token) => { return request( @@ -42,9 +45,11 @@ const fetcher = (variables, token) => { }; /** - * @param {string} username - * @param {string[]} exclude_repo - * @returns {Promise} + * Fetch top languages for a given username. + * + * @param {string} username Github username. + * @param {string[]} exclude_repo List of repositories to exclude. + * @returns {Promise} Top languages data. */ async function fetchTopLanguages(username, exclude_repo = []) { if (!username) throw new MissingParamError(["username"]); diff --git a/src/fetchers/wakatime-fetcher.js b/src/fetchers/wakatime-fetcher.js index 97adcdc..fa1f3d8 100644 --- a/src/fetchers/wakatime-fetcher.js +++ b/src/fetchers/wakatime-fetcher.js @@ -2,8 +2,10 @@ import axios from "axios"; import { MissingParamError } from "../common/utils.js"; /** - * @param {{username: string, api_domain: string, range: string}} props - * @returns {Promise} + * WakaTime data fetcher. + * + * @param {{username: string, api_domain: string, range: string}} props Fetcher props. + * @returns {Promise} WakaTime data response. */ const fetchWakatimeStats = async ({ username, api_domain, range }) => { if (!username) throw new MissingParamError(["username"]); diff --git a/src/getStyles.js b/src/getStyles.js index 3c77787..79692e8 100644 --- a/src/getStyles.js +++ b/src/getStyles.js @@ -1,6 +1,9 @@ // @ts-check /** - * @param {number} value + * Calculates progress along the boundary of the circle i.e it's circumference. + * + * @param {number} value The rank value to calculate progress for. + * @returns {number} Progress value. */ const calculateCircleProgress = (value) => { const radius = 40; @@ -13,9 +16,11 @@ const calculateCircleProgress = (value) => { }; /** + * Retrieves the animation to display progress along the circumference of circle + * from the beginning to the given value in a clockwise direction. * - * @param {{progress: number}} param0 - * @returns + * @param {{progress: number}} progress The progress value to animate to. + * @returns {string} Progress animation css. */ const getProgressAnimation = ({ progress }) => { return ` @@ -30,6 +35,11 @@ const getProgressAnimation = ({ progress }) => { `; }; +/** + * Retrieves css animations for a card. + * + * @returns {string} Animation css. + */ const getAnimations = () => { return ` /* Animations */ @@ -53,13 +63,15 @@ const getAnimations = () => { }; /** - * @param {{ - * titleColor?: string | string[] - * textColor?: string | string[] - * iconColor?: string | string[] - * show_icons?: boolean; - * progress?: number; - * }} args + * Retrieves CSS styles for a card. + * + * @param {Object[]} colors The colors to use for the card. + * @param {string} colors.titleColor The title color. + * @param {string} colors.textColor The text color. + * @param {string} colors.iconColor The icon color. + * @param {boolean} colors.show_icons Whether to show icons. + * @param {number} colors.progress The progress value to animate to. + * @returns {string} Card CSS styles. */ const getStyles = ({ titleColor, diff --git a/src/translations.js b/src/translations.js index 3f931bc..b71d37f 100644 --- a/src/translations.js +++ b/src/translations.js @@ -1,5 +1,12 @@ import { encodeHTML } from "./common/utils.js"; +/** + * Retrieves stat card labels in the available locales. + * + * @param {string} name The name of the locale. + * @param {string} apostrophe Whether to use apostrophe or not. + * @returns {Object} The locales object. + */ const statCardLocales = ({ name, apostrophe }) => { const encodedName = encodeHTML(name); return { @@ -354,6 +361,12 @@ const wakatimeCardLocales = { const availableLocales = Object.keys(repoCardLocales["repocard.archived"]); +/** + * Checks whether the locale is available or not. + * + * @param {string} locale The locale to check. + * @returns {boolean} Boolean specifying whether the locale is available or not. + */ function isLocaleAvailable(locale) { return availableLocales.includes(locale.toLowerCase()); }