Merge pull request #10 from AgapeToolkit/update-docs

update typedocs

Author: MaverikMinett

src/lib/functions/camelize.ts

@@ -2,23 +2,30 @@
  * Converts a string to camelCase.
  * Removes all non-alphanumeric separators and capitalizes each word except the first.
  *
- * @param input The input string to be camelized.
- * @returns The camelCased version of the input string.
+ * ## Usage
  *
- * @example
+ * ```ts
  * camelize("hello world"); // "helloWorld"
+ * ```
  *
- * @example
+ * ```ts
  * camelize("Hello_world"); // "helloWorld"
+ * ```
  *
- * @example
+ * ```ts
  * camelize("API_response_code"); // "apiResponseCode"
+ * ```
  *
- * @example
+ * ```ts
  * camelize("user-42-profile"); // "user42Profile"
+ * ```
  *
- * @example
+ * ```ts
  * camelize("ThisIsALongVariableName"); // "thisIsALongVariableName"
+ * ```
+ *
+ * @param input The input string to be camelized.
+ * @returns The camelCased version of the input string.
  */
 export function camelize(input: string): string {
   const parts = input

src/lib/functions/kebabify.ts

@@ -6,26 +6,34 @@ import { PLACEHOLDER } from "../private/constants";
  * Replaces spaces, underscores, camelCase transitions, and other separators with dashes.
  * It also preserves version tokens like "v2" and lowercases the result.
  *
- * @param input A string to be converted to kebab-case.
- * @returns The kebab-cased version of the input string.
+ * ## Usage
  *
- * @example
+ * ```ts
  * kebabify("hello world"); // "hello-world"
+ * ```
  *
- * @example
+ * ```ts
  * kebabify("first_name"); // "first-name"
+ * ```
  *
- * @example
+ * ```ts
  * kebabify("userProfile42"); // "user-profile-42"
+ * ```
  *
- * @example
+ * ```ts
  * kebabify("APIResponseV2"); // "api-response-v2"
+ * ```
  *
- * @example
+ * ```ts
  * kebabify("HTML5_Parser v3"); // "html-5-parser-v3"
+ * ```
  *
- * @example
+ * ```ts
  * kebabify("  Leading_and trailing   "); // "leading-and-trailing"
+ * ```
+ *
+ * @param input A string to be converted to kebab-case.
+ * @returns The kebab-cased version of the input string.
  */
 export function kebabify(input: string): string {
   const versionMatches: string[] = [];
@@ -35,7 +43,7 @@ export function kebabify(input: string): string {
     const id = versionMatches.length;
     versionMatches.push(match);
     return `-${PLACEHOLDER}-${id}`;
-  });  
+  });
 
   let kebabed = preserved
     .replace(/([a-z0-9])([A-Z])/g, '$1-$2')          // camelCase
@@ -55,4 +63,4 @@ export function kebabify(input: string): string {
 
   // Step 4: lowercase entire result
   return kebabed.toLowerCase();
-}
+}

src/lib/functions/pascalize.ts

@@ -4,23 +4,30 @@
  * Removes non-alphanumeric characters, splits on casing and digits,
  * capitalizes each word, and strips leading/trailing separators.
  *
- * @param input A string to be returned in PascalCase.
- * @returns The PascalCased version of the input string.
+ * ## Usage
  *
- * @example
+ * ```ts
  * pascalize("hello world"); // "HelloWorld"
+ * ```
  *
- * @example
+ * ```ts
  * pascalize("first_name"); // "FirstName"
+ * ```
  *
- * @example
+ * ```ts
  * pascalize("user42Profile"); // "User42Profile"
+ * ```
  *
- * @example
+ * ```ts
  * pascalize("API response code"); // "ApiResponseCode"
+ * ```
  *
- * @example
+ * ```ts
  * pascalize("  messy__input--string  "); // "MessyInputString"
+ * ```
+ *
+ * @param input A string to be returned in PascalCase.
+ * @returns The PascalCased version of the input string.
  */
 export function pascalize(input: string): string {
   const parts = input

src/lib/functions/pluralize.ts

@@ -11,41 +11,54 @@ import { preserveCasing } from '../private/util';
  *
  * The output preserves the casing of the input, especially the prefix.
  *
- * @param word A singular word to be pluralized.
- * @returns The plural form of the input word.
+ * ## Usage
  *
- * @example
+ * ```ts
  * pluralize("city"); // "cities"
+ * ```
  *
- * @example
+ * ```ts
  * pluralize("box"); // "boxes"
+ * ```
  *
- * @example
+ * ```ts
  * pluralize("child"); // "children"
+ * ```
  *
- * @example
+ * ```ts
  * pluralize("person"); // "people"
+ * ```
  *
- * @example
+ * ```ts
  * pluralize("API"); // "APIs"
+ * ```
  *
- * @example
+ * ```ts
  * pluralize("ID"); // "IDs"
+ * ```
  *
- * @example
+ * ```ts
  * pluralize("File"); // "Files"
+ * ```
  *
- * @example
+ * ```ts
  * pluralize("buzz"); // "buzzes"
+ * ```
  *
- * @example
+ * ```ts
  * pluralize("CPU"); // "CPUs"
+ * ```
  *
- * @example
+ * ```ts
  * pluralize("DOG"); // "DOGS"
+ * ```
+ *
+ * ```ts
+ * pluralize("A"); // "As"
+ * ```
  *
- * @example
- * pluralize("A"); // "as"
+ * @param word A singular word to be pluralized.
+ * @returns The plural form of the input word.
  */
 export function pluralize(word: string): string {
   if (word.length === 0) return '';

src/lib/functions/quantify.ts

@@ -3,37 +3,46 @@ import { pluralize } from './pluralize';
 /**
  * Formats a number with a unit, automatically pluralizing the unit based on the count.
  *
- * If the `count` is exactly 1, the singular `unit` is used. Otherwise, it either uses
- * the provided `plural` form or calls `pluralize(unit)` to generate one.
+ * If the `<property>count` is exactly 1, the singular `<property>unit` is used.
+ * Otherwise, it either uses  the provided `<property>plural` form or calls
+ * <code><reference>pluralize</reference>(<property>unit</property>)</code>
+ * to generate one.
  *
- * @param count Number of units, as a number or numeric string.
- * @param unit Label for the singular unit (e.g., "apple").
- * @param plural Optional plural label. If not provided, the unit is pluralized automatically.
- * @returns A formatted string in the form `x unit(s)`.
+ * ## Usage
  *
- * @example
+ * ```ts
  * quantify(1, "apple"); // "1 apple"
+ * ```
  *
- * @example
+ * ```ts
  * quantify(3, "apple"); // "3 apples"
+ * ```
  *
- * @example
- * quantify("2", "box"); // "2 boxes"
+ * ```ts
+ * quantify("02", "box"); // "02 boxes"
+ * ```
  *
- * @example
+ * ```ts
  * quantify(1, "child", "children"); // "1 child"
+ * ```
  *
- * @example
+ * ```ts
  * quantify(2, "child", "children"); // "2 children"
+ * ```
  *
- * @example
+ * ```ts
  * quantify(5, "CPU"); // "5 CPUs"
+ * ```
+ *
+ * @param count Number of units, as a number or numeric string.
+ * @param unit Label for the singular unit (e.g., "apple").
+ * @param plural Optional plural label. If not provided, the unit is pluralized automatically.
+ * @returns A formatted string in the form `x unit(s)`.
  */
-export function quantify(count: number|string, unit: string, plural?: string) {
+export function quantify(count: number | string, unit: string, plural?: string) {
   const value = typeof count == 'number' ? count : Number(count);
 
   const label = value === 1 ? unit : plural === undefined ? pluralize(unit) : plural;
 
   return `${count} ${label}`
-
-}
+}

src/lib/functions/singularize.ts

@@ -11,29 +11,38 @@ import { preserveCasing } from '../private/util';
  *
  * Preserves the casing of the original input, including acronyms or title case.
  *
- * @param word Plural word to be converted to singular.
- * @returns The singular form of the input word.
+ * ## Usage
  *
- * @example
+ * ```ts
  * singularize("cities"); // "city"
+ * ```
  *
- * @example
+ * ```ts
  * singularize("boxes"); // "box"
+ * ```
  *
- * @example
+ * ```ts
  * singularize("children"); // "child"
+ * ```
  *
- * @example
+ * ```ts
  * singularize("teeth"); // "tooth"
+ * ```
  *
- * @example
+ * ```ts
  * singularize("dogs"); // "dog"
+ * ```
  *
- * @example
+ * ```ts
  * singularize("BUZZES"); // "BUZZ"
+ * ```
  *
- * @example
+ * ```ts
  * singularize("IDs"); // "ID"
+ * ```
+ *
+ * @param word Plural word to be converted to singular.
+ * @returns The singular form of the input word.
  */
 export function singularize(word: string): string {
   const lower = word.toLowerCase();
@@ -83,4 +92,4 @@ export function singularize(word: string): string {
 
   // Default: assume word is already singular
   return word;
-}
+}

src/lib/functions/snakify.ts

@@ -7,23 +7,30 @@ import { PLACEHOLDER } from '../private/constants';
  * removes special characters, preserves embedded version tokens (like "v2"),
  * and lowercases the result.
  *
- * @param input A string to be converted to snake_case.
- * @returns The snake_cased version of the input.
+ * ## Usage
  *
- * @example
+ * ```ts
  * snakify("hello world"); // "hello_world"
+ * ```
  *
- * @example
+ * ```ts
  * snakify("UserProfileV2"); // "user_profile_v2"
+ * ```
  *
- * @example
+ * ```ts
  * snakify("HTML5 Parser"); // "html_5_parser"
+ * ```
  *
- * @example
+ * ```ts
  * snakify("  messy-input_string  "); // "messy_input_string"
+ * ```
  *
- * @example
+ * ```ts
  * snakify("ReportV3Final"); // "report_v3_final"
+ * ```
+ *
+ * @param input A string to be converted to snake_case.
+ * @returns The snake_cased version of the input.
  */
 export function snakify(input: string): string {
   const versionMatches: string[] = [];