refactor: added JSDoc comments to exported functions in locales.ts (#589)

Author: sidhuiwnl

.changeset/new-buses-carry.md

@@ -0,0 +1,2 @@
+---
+---

.gitignore

@@ -14,6 +14,7 @@ node_modules
 
 # Testing
 coverage
+.idea
 
 # Turbo
 .turbo

packages/spec/src/locales.ts

@@ -222,6 +222,20 @@ export const localeCodeSchema = Z.string().refine((value) => localeCodes.include
   message: "Invalid locale code",
 });
 
+
+/**
+ * Resolves a locale code to its full locale representation.
+ *
+ *  If the provided locale code is already a full locale code, it returns as is.
+ *  If the provided locale code is a short locale code, it returns the first corresponding full locale.
+ *  If the locale code is not found, it throws an error.
+ *
+ * @param {localeCodes} value - The locale code to resolve (either short or full)
+ * @return {LocaleCodeFull} The resolved full locale code
+ * @throws {Error} If the provided locale code is invalid.
+ */
+
+
 export const resolveLocaleCode = (value: LocaleCode): LocaleCodeFull => {
   const existingFullLocaleCode = Object.values(localeMap)
     .flat()
@@ -240,6 +254,15 @@ export const resolveLocaleCode = (value: LocaleCode): LocaleCodeFull => {
   throw new Error(`Invalid locale code: ${value}`);
 };
 
+/**
+ * Determines the delimiter used in a locale code
+ *
+ * @param {string} locale - the locale string (e.g.,"en_US","en-GB")
+ * @return { string | null} - The delimiter ("_" or "-") if found, otherwise `null`.
+ */
+
+
+
 export const getLocaleCodeDelimiter = (locale: string): LocaleDelimiter => {
   if (locale.includes("_")) {
     return "_";
@@ -250,6 +273,14 @@ export const getLocaleCodeDelimiter = (locale: string): LocaleDelimiter => {
   }
 };
 
+/**
+ * Replaces the delimiter in a locale string with the specified delimiter.
+ *
+ * @param {string}locale - The locale string (e.g.,"en_US", "en-GB").
+ * @param {"-" | "_" | null} [delimiter] - The new delimiter to replace the existing one.
+ * @returns {string} The locale string with the replaced delimiter, or the original locale if no delimiter is provided.
+ */
+
 export const resolveOverriddenLocale = (locale: string, delimiter?: LocaleDelimiter): string => {
   if (!delimiter) {
     return locale;
@@ -263,6 +294,14 @@ export const resolveOverriddenLocale = (locale: string, delimiter?: LocaleDelimi
   return locale.replace(currentDelimiter, delimiter);
 };
 
+/**
+ * Normalizes a locale string by replacing underscores with hyphens
+ * and removing the "r" in certain regional codes (e.g., "fr-rCA" → "fr-CA")
+ *
+ * @param {string} locale - The locale string (e.g.,"en_US", "en-GB").
+ * @return {string} The normalized locale string.
+ */
+
 export function normalizeLocale(locale: string): string {
   return locale.replaceAll("_", "-").replace(/([a-z]{2,3}-)r/, "$1");
 }