fix: adding doc strings to files in src folder where it was missing (#2129)

* fix: adding doc strings to files in src folder where it was missing

* refactor: add docstrings

* style: run formatter

Co-authored-by: rickstaa <rick.staa@outlook.com>

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<import('Axios').AxiosResponse>} The response.
  */
 const fetcher = (variables, token) => {
   return request(
@@ -51,9 +54,11 @@ const fetcher = (variables, token) => {
 const urlExample = "/api/pin?username=USERNAME&amp;repo=REPO_NAME";
 
 /**
- * @param {string} username
- * @param {string} reponame
- * @returns {Promise<import("./types").RepositoryData>}
+ * Fetch repository data.
+ *
+ * @param {string} username Github username.
+ * @param {string} reponame Github repository name.
+ * @returns {Promise<import("./types").RepositoryData>} Repository data.
  */
 async function fetchRepo(username, reponame) {
   if (!username && !reponame) {

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<import('../common/types').StatsFetcherResponse>} 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<import('../common/types').StatsFetcherResponse>} 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<number>} 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<number>} 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<import("./types").StatsData>}
+ * 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<import("./types").StatsData>} Stats data.
  */
 async function fetchStats(
   username,

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<import('../common/types').StatsFetcherResponse>} 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<import("./types").TopLangData>}
+ * Fetch top languages for a given username.
+ *
+ * @param {string} username Github username.
+ * @param {string[]} exclude_repo List of repositories to exclude.
+ * @returns {Promise<import("./types").TopLangData>} Top languages data.
  */
 async function fetchTopLanguages(username, exclude_repo = []) {
   if (!username) throw new MissingParamError(["username"]);

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<WakaTimeData>}
+ * WakaTime data fetcher.
+ *
+ * @param {{username: string, api_domain: string, range: string}} props Fetcher props.
+ * @returns {Promise<WakaTimeData>} WakaTime data response.
  */
 const fetchWakatimeStats = async ({ username, api_domain, range }) => {
   if (!username) throw new MissingParamError(["username"]);