feat: require JSDoc in new api (#50429)

Co-authored-by: Oliver Eyton-Williams <ojeytonwilliams@gmail.com>

api/src/utils/common-challenge-functions.ts

@@ -65,6 +65,18 @@ type CompletedChallenge = {
   files?: CompletedChallengeFile[];
 };
 
+/**
+ * Helper function to update a user's challenge data. Used in challenge
+ * submission endpoints.
+ *
+ * @deprecated Create specific functions for each submission endpoint.
+ * @param fastify The Fastify instance.
+ * @param user The existing user record.
+ * @param challengeId The id of the submitted challenge.
+ * @param _completedChallenge The challenge submission.
+ * @param timezone The user's timezone.
+ * @returns Information about the update.
+ */
 export async function updateUserChallengeData(
   fastify: FastifyInstance,
   user: user,

api/src/utils/error-formatting.ts

@@ -9,7 +9,12 @@ export type FormattedError = {
     | 'You have to complete the project before you can submit a URL.';
 };
 
-// This only formats invalid challenge submission for now.
+/**
+ * Format invalid challenge submission errors.
+ *
+ * @param errors An array of validation errors.
+ * @returns Formatted errors that can be used in the response.
+ */
 export const formatValidationError = (
   errors: ErrorObject[]
 ): FormattedError => {

api/src/utils/get-challenges.ts

@@ -20,6 +20,10 @@ interface CurriculumProps {
   blocks: Record<string, Block>;
 }
 
+/**
+ * Get all the challenges from the curriculum.
+ * @returns An array of challenges.
+ */
 export function getChallenges() {
   const superBlockKeys = Object.values(SuperBlocks);
   const typedCurriculum: Curriculum = curriculum as Curriculum;

api/src/utils/index.ts

@@ -1,5 +1,11 @@
 import { randomBytes, createHash } from 'crypto';
 
+/**
+ * Utility to encode a buffer to a base64 URI.
+ *
+ * @param buf The buffer to encode.
+ * @returns The encoded string.
+ */
 export function base64URLEncode(buf: Buffer): string {
   return buf
     .toString('base64')

api/src/utils/normalize.ts

@@ -9,6 +9,12 @@ type NoNullProperties<T> = {
   [P in keyof T]: NullToUndefined<T[P]>;
 };
 
+/**
+ * Converts a Twitter handle or URL to a URL.
+ *
+ * @param handleOrUrl Twitter handle or URL.
+ * @returns Twitter URL.
+ */
 export const normalizeTwitter = (
   handleOrUrl: string | null
 ): string | undefined => {
@@ -23,6 +29,12 @@ export const normalizeTwitter = (
   return url ?? handleOrUrl;
 };
 
+/**
+ * Ensure that the user's profile UI settings are valid.
+ *
+ * @param maybeProfileUI A null or the user's profile UI settings.
+ * @returns The input with nulls removed or a default value if there is no input.
+ */
 export const normalizeProfileUI = (
   maybeProfileUI: ProfileUI | null
 ): NoNullProperties<ProfileUI> => {
@@ -42,6 +54,12 @@ export const normalizeProfileUI = (
       };
 };
 
+/**
+ * Remove all the null properties from an object.
+ *
+ * @param obj Any object.
+ * @returns The input with nulls removed.
+ */
 export const removeNulls = <T extends Record<string, unknown>>(
   obj: T
 ): NoNullProperties<T> =>
@@ -65,6 +83,12 @@ type NormalizedChallenge = {
   solution?: string;
 };
 
+/**
+ * Remove all the null properties from a CompletedChallenge array.
+ *
+ * @param completedChallenges The CompletedChallenge array.
+ * @returns The input with nulls removed.
+ */
 export const normalizeChallenges = (
   completedChallenges: CompletedChallenge[]
 ): NormalizedChallenge[] => {

api/src/utils/progress.ts

@@ -1,5 +1,11 @@
 export type ProgressTimestamp = number | { timestamp: number } | null;
 
+/**
+ * Converts a ProgressTimestamp array to a object with keys based on the timestamps.
+ *
+ * @param progressTimestamps The ProgressTimestamp array.
+ * @returns The object with keys based on the timestamps.
+ */
 export const getCalendar = (
   progressTimestamps: ProgressTimestamp[] | null
 ): Record<string, 1> => {
@@ -17,6 +23,12 @@ export const getCalendar = (
   return calendar;
 };
 
+/**
+ * Converts a ProgressTimestamp array to an integer number of points.
+ *
+ * @param progressTimestamps The ProgressTimestamp array.
+ * @returns The number of points.
+ */
 export const getPoints = (
   progressTimestamps: ProgressTimestamp[] | null
 ): number => {

api/src/utils/user-token.ts

@@ -2,6 +2,12 @@ import jwt from 'jsonwebtoken';
 
 import { JWT_SECRET } from './env';
 
+/**
+ * Encode an id into a JWT (the naming suggests it's a user token, but it's the
+ * id of the UserToken document).
+ * @param userToken A token id to encode.
+ * @returns An encoded object with the userToken property.
+ */
 export function encodeUserToken(userToken: string): string {
   return jwt.sign({ userToken }, JWT_SECRET);
 }

api/src/utils/validation.ts

@@ -2,5 +2,11 @@ import { ObjectId } from 'mongodb';
 
 // This is trivial, but makes it simple to refactor if we swap monogodb for
 // bson, say.
+
+/**
+ * Checks if a string is a valid MongoDB ObjectID.
+ * @param id A string to check.
+ * @returns A boolean indicating if the string is a valid MongoDB ObjectID.
+ */
 export const isObjectID = (id?: string): boolean =>
   id ? ObjectId.isValid(id) : false;