Merge pull request #230 from takker99:doc-test

refactor(test): Move tests into JSDoc comments

Author: takker99

text.test.ts

@@ -1,6 +1,16 @@
+// deno-lint-ignore-file no-irregular-whitespace
 import { isString } from "@core/unknownutil/is/string";
 
 /** Count the number of leading whitespace characters (indentation level)
+ *
+ * ```ts
+ * import { assertEquals } from "@std/assert/equals";
+ *
+ * assertEquals(getIndentCount("sample text "), 0);
+ * assertEquals(getIndentCount("  sample text "), 2);
+ * assertEquals(getIndentCount("　　 sample text"), 3);
+ * assertEquals(getIndentCount("\t \t　　sample text"), 5);
+ * ```
  *
  * @param text - The input {@linkcode string} to analyze
  * @returns The {@linkcode number} of leading whitespace characters

text.ts

@@ -1,17 +1,58 @@
+// deno-lint-ignore-file no-irregular-whitespace
 /** Convert a string to titleLc format
  *
- * - Converts spaces (` `) to underscores (`_`)
+ * -
  * - Converts uppercase to lowercase
  *
  * Primarily used for comparing links for equality
  *
+ * @example Converts spaces (` `) to underscores (`_`)
+ * ```ts
+ * import { assertEquals } from "@std/assert/equals";
+ *
+ * assertEquals(toTitleLc("sample text"), "sample_text");
+ * assertEquals(
+ *   toTitleLc("空白入り タイトル"),
+ *   "空白入り_タイトル",
+ * );
+ * assertEquals(
+ *   toTitleLc(" 前後にも 空白入り _タイトル "),
+ *   "_前後にも_空白入り__タイトル_",
+ * );
+ * ```
+ *
+ * @example Converts uppercase to lowercase
+ * ```ts
+ * import { assertEquals } from "@std/assert/equals";
+ *
+ * assertEquals(toTitleLc("Scrapbox-Gyazo"), "scrapbox-gyazo");
+ * assertEquals(
+ *   toTitleLc("全角アルファベット「Ｓｃｒａｐｂｏｘ」も変換できる"),
+ *   "全角アルファベット「ｓｃｒａｐｂｏｘ」も変換できる",
+ * );
+ * assertEquals(
+ *   toTitleLc("Scrapbox is one of the products powered by Nota inc."),
+ *   "scrapbox_is_one_of_the_products_powered_by_nota_inc.",
+ * );
+ * ```
+ *
  * @param text - String to convert
  * @returns A {@linkcode string} containing the converted text in titleLc format
  */
 export const toTitleLc = (text: string): string =>
   text.replaceAll(" ", "_").toLowerCase();
 
-/** Convert underscores (`_`) to single-byte spaces
+/** Convert underscores (`_`) to single-byte spaces (` `)
+ *
+ * ```ts
+ * import { assertEquals } from "@std/assert/equals";
+ *
+ * assertEquals(revertTitleLc("sample_text"), "sample text");
+ * assertEquals(
+ *   revertTitleLc("Title_with underscore"),
+ *   "Title with underscore",
+ * );
+ * ```
  *
  * @param text - String to convert
  * @returns A {@linkcode string} with underscores converted to spaces
@@ -20,6 +61,13 @@ export const revertTitleLc = (text: string): string =>
   text.replaceAll("_", " ");
 
 /** Encode a title into a URI-safe format
+ *
+ * ```ts
+ * import { assertEquals } from "@std/assert/equals";
+ *
+ * assertEquals(encodeTitleURI("sample text"), "sample_text");
+ * assertEquals(encodeTitleURI(":title:"), ":title%3A");
+ * ```
  *
  * @param title - Title to encode
  * @returns A {@linkcode string} containing the URI-safe encoded title
@@ -41,6 +89,60 @@ const noEncodeChars = '@$&+=:;",';
 const noTailChars = ':;",';
 
 /** Convert a title to a URI-safe format while minimizing percent encoding
+ *
+ * @example Only words
+ * ```ts
+ * import { assertEquals } from "@std/assert/equals";
+ *
+ * assertEquals(
+ *   toReadableTitleURI("Normal_TitleAAA"),
+ *   "Normal_TitleAAA",
+ * );
+ * ```
+ *
+ * @example With spaces
+ * ```ts
+ * import { assertEquals } from "@std/assert/equals";
+ *
+ * assertEquals(
+ *   toReadableTitleURI("Title with Spaces"),
+ *   "Title_with_Spaces",
+ * );
+ * ```
+ *
+ * @example With special characters
+ * ```ts
+ * import { assertEquals } from "@std/assert/equals";
+ *
+ * assertEquals(
+ *   toReadableTitleURI("Title with special characters: /?{}^|<>%"),
+ *  "Title_with_special_characters:_%2F%3F%7B%7D%5E%7C%3C%3E%25",
+ * );
+ * ```
+ *
+ * @example With multibyte characters
+ * ```ts
+ * import { assertEquals } from "@std/assert/equals";
+ *
+ * assertEquals(
+ *   toReadableTitleURI("日本語_(絵文字✨つき)　タイトル"),
+ *   "日本語_(絵文字✨つき)　タイトル",
+ * );
+ * ```
+ *
+ * @example With percent encoding
+ * ```ts
+ * import { assertEquals } from "@std/assert/equals";
+ *
+ * assertEquals(
+ *   toReadableTitleURI("スラッシュ/は/percent encoding対象の/文字です"),
+ *   "スラッシュ%2Fは%2Fpercent_encoding対象の%2F文字です",
+ * );
+ * assertEquals(
+ *   toReadableTitleURI("%2Fなども/と同様percent encodingされる"),
+ *   "%252Fなども%2Fと同様percent_encodingされる",
+ * );
+ * ```
  *
  * @param title - Title to convert
  * @returns A {@linkcode string} containing the URI-safe title with minimal percent encoding

title.test.ts

@@ -1,2 +1,21 @@
+/**
+ * Compare two arrays to see if they are the same.
+ *
+ * This function only checks each element's reference, not the content.
+ *
+ * ```ts
+ * import { assert } from "@std/assert/assert";
+ *
+ * assert(isSameArray([1, 2, 3], [1, 2, 3]));
+ * assert(isSameArray([1, 2, 3], [3, 2, 1]));
+ * assert(!isSameArray([1, 2, 3], [3, 2, 3]));
+ * assert(!isSameArray([1, 2, 3], [1, 2]));
+ * assert(isSameArray([], []));
+ * ```
+ *
+ * @param a
+ * @param b
+ * @returns
+ */
 export const isSameArray = <T>(a: T[], b: T[]): boolean =>
   a.length === b.length && a.every((x) => b.includes(x));

title.ts

@@ -1,3 +1,19 @@
+/**
+ * Suggest a new title that is already in use.
+ *
+ * ```ts
+ * import { assertEquals } from "@std/assert/equals";
+ *
+ * assertEquals(suggestUnDupTitle("title"), "title_2");
+ * assertEquals(suggestUnDupTitle("title_2"), "title_3");
+ * assertEquals(suggestUnDupTitle("title_10"), "title_11");
+ * assertEquals(suggestUnDupTitle("title_10_3"), "title_10_4");
+ * assertEquals(suggestUnDupTitle("another_title_5"), "another_title_6");
+ * ```
+ *
+ * @param title - The title to suggest a new name for
+ * @returns
+ */
 export const suggestUnDupTitle = (title: string): string => {
   const matched = title.match(/(.+?)(?:_(\d+))?$/);
   const title_ = matched?.[1] ?? title;