Add jsdoc to hiscores and helper functions.

src/hiscores.ts

@@ -30,6 +30,12 @@ import {
   BOSSES
 } from './utils';
 
+/**
+ * Screen scrapes the hiscores to get the formatted rsn of a player.
+ *
+ * @param rsn Username of the player.
+ * @returns Formatted version of the rsn.
+ */
 export async function getRSNFormat(rsn: string): Promise<string> {
   if (typeof rsn !== 'string') {
     throw Error('RSN must be a string');
@@ -56,6 +62,12 @@ export async function getRSNFormat(rsn: string): Promise<string> {
   }
 }
 
+/**
+ * Parses CSV string of raw stats and returns a stats object.
+ *
+ * @param csv Raw CSV from the official OSRS API.
+ * @returns Parsed stats object.
+ */
 export function parseStats(csv: string): Stats {
   const splitCSV = csv
     .split('\n')
@@ -128,6 +140,15 @@ export function parseStats(csv: string): Stats {
   return stats;
 }
 
+/**
+ * Fetches stats from the OSRS API and consolidates the info into a player object.
+ *
+ * **Note:** This function will make up to 5 separate network requests.
+ * As such, it is highly subject to the performance of the official OSRS API.
+ *
+ * @param rsn Username of the player.
+ * @returns Player object.
+ */
 export async function getStats(rsn: string): Promise<Player> {
   if (typeof rsn !== 'string') {
     throw Error('RSN must be a string');
@@ -205,6 +226,13 @@ export async function getStats(rsn: string): Promise<Player> {
   throw Error('Player not found');
 }
 
+/**
+ * Fetches stats from the OSRS API and returns them as an object.
+ *
+ * @param rsn Username of the player.
+ * @param mode Gamemode to fetch ranks for.
+ * @returns Stats object.
+ */
 export async function getStatsByGamemode(
   rsn: string,
   mode: Gamemode = 'main'
@@ -267,6 +295,14 @@ export async function getSkillPage(
   return players;
 }
 
+/**
+ * Screen scrapes a hiscores page of an activity or boss and returns an array of up to 25 players.
+ *
+ * @param activity Name of the activity or boss to fetch hiscores for.
+ * @param mode Gamemode to fetch ranks for.
+ * @param page Page number.
+ * @returns Array of `PlayerActivityRow` objects.
+ */
 export async function getActivityPage(
   activity: ActivityName,
   mode: Gamemode = 'main',

src/utils/helpers.ts

@@ -9,14 +9,36 @@ import {
   ACTIVITIES
 } from './constants';
 
+/**
+ * Will generate a stats URL for the official OSRS API.
+ *
+ * @param gamemode Gamemode to fetch ranks for.
+ * @param rsn Username of the player.
+ * @returns Encoded stats URL.
+ */
 export const getStatsURL = (gamemode: Gamemode, rsn: string) =>
   `${GAMEMODE_URL[gamemode]}${STATS_URL}${encodeURIComponent(rsn)}`;
 
+/**
+ * Will generate a player table URL for the official OSRS hiscores website.
+ *
+ * @param gamemode Gamemode to fetch ranks for.
+ * @param rsn Username of the player.
+ * @returns Encoded player table URL.
+ */
 export const getPlayerTableURL = (gamemode: Gamemode, rsn: string) =>
   `${GAMEMODE_URL[gamemode]}${SCORES_URL}table=0&user=${encodeURIComponent(
     rsn
   )}`;
 
+/**
+ * Will generate a skill table URL for the official OSRS hiscores website.
+ *
+ * @param gamemode Gamemode to fetch ranks for.
+ * @param skill Skill to fetch ranks for.
+ * @param page Page number.
+ * @returns
+ */
 export const getSkillPageURL = (
   gamemode: Gamemode,
   skill: SkillName,
@@ -26,6 +48,14 @@ export const getSkillPageURL = (
     skill
   )}&page=${page}`;
 
+/**
+ * Will generate an activity table URL for the official OSRS hiscores website.
+ *
+ * @param gamemode Gamemode to fetch ranks for.
+ * @param activity Activity or boss to fetch ranks for.
+ * @param page Page number.
+ * @returns
+ */
 export const getActivityPageURL = (
   gamemode: Gamemode,
   activity: ActivityName,
@@ -37,17 +67,35 @@ export const getActivityPageURL = (
     activity
   )}&page=${page}`;
 
+/**
+ * Extracts a number from an OSRS hiscores table cell element.
+ *
+ * @param el OSRS hiscores table cell element.
+ * @returns Number parsed from cell text.
+ */
 export const numberFromElement = (el: Element | null) => {
-  const { innerHTML } = el || {};
+  const { innerHTML } = el ?? {};
   const number = innerHTML?.replace(/[\n|,]/g, '') ?? '-1';
   return parseInt(number, 10);
 };
 
+/**
+ * Extracts a RSN from an OSRS hiscores table cell element.
+ *
+ * @param el OSRS hiscores table cell element.
+ * @returns RSN parsed from cell text.
+ */
 export const rsnFromElement = (el: Element | null) => {
-  const { innerHTML } = el || {};
-  return innerHTML?.replace(/\uFFFD/g, ' ') || '';
+  const { innerHTML } = el ?? {};
+  return innerHTML?.replace(/\uFFFD/g, ' ') ?? '';
 };
 
+/**
+ * Will run an Axios `GET` request against a given URL after injecting a `User-Agent` header.
+ *
+ * @param url URL to run a `GET` request against.
+ * @returns Axios response.
+ */
 export const httpGet = (url: string) =>
   axios.get(url, {
     headers: {