test: - Improve jsdoc blocks for test helpers

Author: claremacrae

tests/Obsidian/SimulatedFile.ts

@@ -10,6 +10,22 @@ import { setCurrentCacheFile } from '../__mocks__/obsidian';
  * - See also {@link getTasksFileFromMockData} and {@link listPathAndData}.
  */
 
+/**
+ * Represent Obsidian-specific data read from a JSON file in `tests/Obsidian/__test_data__/`
+ *
+ * See the related functions that uses some or all of this data:
+ * - {@link readTasksFromSimulatedFile}
+ * - {@link getTasksFileFromMockData}
+ * - {@link listPathAndData}
+ *
+ * @property cachedMetadata - Snapshot of Obsidian's CachedMetadata for the source note.
+ * @property filePath - The path of the source note in the test vault.
+ * @property fileContents - The complete content of the source note.
+ * @property getAllTags - Used for mocking the result of `getAllTags()` in tests.
+ * @property parseFrontMatterTags - Used for mocking the result of `parseFrontMatterTags()` in tests.
+ *
+ * For more info, see https://publish.obsidian.md/tasks-contributing/Testing/Using+Obsidian+API+in+tests.
+ */
 export interface SimulatedFile {
     cachedMetadata: CachedMetadata;
     filePath: string;
@@ -19,8 +35,20 @@ export interface SimulatedFile {
 }
 
 /**
- For explanations on how to test code that is using Obsidian API
- refer to https://publish.obsidian.md/tasks-contributing/Testing/Using+Obsidian+API+in+tests
+ * Read tasks from Obsidian-specific data read from a JSON file in `tests/Obsidian/__test_data__`.
+ *
+ * @param {SimulatedFile} testData - Read from a JSON file in `tests/Obsidian/__test_data__`
+ * @return {ParsedTasks} The parsed tasks extracted from the file content.
+ *
+ * Example use:
+ * ```typescript
+ * import numbered_list_items_with_paren from './__test_data__/numbered_list_items_with_paren.json';
+ * ...
+ *         const data = numbered_list_items_with_paren;
+ *         const tasks = readTasksFromSimulatedFile(data);
+ * ```
+ *
+ * For more info, see https://publish.obsidian.md/tasks-contributing/Testing/Using+Obsidian+API+in+tests.
  */
 export function readTasksFromSimulatedFile(testData: SimulatedFile) {
     const logger = logging.getLogger('testCache');

tests/TestingTools/MockDataHelpers.ts

@@ -10,12 +10,74 @@ import type { SimulatedFile } from '../Obsidian/SimulatedFile';
  * - See also {@link SimulatedFile} and {@link readTasksFromSimulatedFile}.
  */
 
+/**
+ * Retrieve a {@link TasksFile} instance from the provided mock data.
+ *
+ * Example use:
+ *
+ * ```typescript
+ * import example_kanban from '../Obsidian/__test_data__/example_kanban.json';
+ *         const data = example_kanban;
+ *         const tasksFile = getTasksFileFromMockData(data);
+ * ```
+ *
+ * @param {any} data - Mock data containing the file information and metadata.
+ *                     This will be a JSON file, read from `tests/Obsidian/__test_data__`
+ * @return {TasksFile} An instance of {@link TasksFile} initialized with the file path and cached metadata.
+ *
+ * For more info, see https://publish.obsidian.md/tasks-contributing/Testing/Using+Obsidian+API+in+tests.
+ */
 export function getTasksFileFromMockData(data: SimulatedFile) {
     setCurrentCacheFile(data);
     const cachedMetadata = data.cachedMetadata as CachedMetadata;
     return new TasksFile(data.filePath, cachedMetadata);
 }
 
+/**
+ * Transform an array of {@link SimulatedFile} objects into an array of tuples containing file paths and data.
+ *
+ * This function is used to prepare {@link allCacheSampleData} for use with jest's it.each().
+ *
+ * ```typescript
+ *     it.each(listPathAndData(allCacheSampleData()))(
+ *         'should be able to read tasks from all mock files: "%s"',
+ *         (path: string, file: any) => {
+ *             const tasks = readTasksFromSimulatedFile(file);
+ *             const files_without_tasks = [
+ *                 'Test Data/docs_sample_for_explain_query_file_defaults.md',
+ *                 'Test Data/non_tasks.md',
+ *             ];
+ *             if (files_without_tasks.includes(path)) {
+ *                 expect(tasks.length).toEqual(0);
+ *             } else {
+ *                 expect(tasks.length).toBeGreaterThan(0);
+ *             }
+ *         },
+ *     );
+ * ```
+ *
+ * It can also be used with specific test files:
+ *
+ * ```typescript
+ *     it.each(
+ *         listPathAndData([
+ *             yaml_custom_number_property, // no tags value in frontmatter
+ *             yaml_tags_field_added_by_obsidian_but_not_populated,
+ *             yaml_tags_had_value_then_was_emptied_by_obsidian,
+ *             yaml_tags_is_empty_list,
+ *             yaml_tags_is_empty,
+ *         ]),
+ *     )('should provide empty list if no tags in frontmatter: "%s"', (_path: string, data: any) => {
+ *         const tasksFile = getTasksFileFromMockData(data);
+ *         expect(tasksFile.frontmatter.tags).toEqual([]);
+ *     });
+ * ```
+ *
+ * @param {SimulatedFile[]} inputs - Array of {@link SimulatedFile} objects.
+ * @returns {[string, SimulatedFile][]} Array of tuples, where each tuple contains [filePath, SimulatedFile]
+ *
+ * For more info, see https://publish.obsidian.md/tasks-contributing/Testing/Using+Obsidian+API+in+tests.
+ */
 export function listPathAndData(inputs: SimulatedFile[]): [string, SimulatedFile][] {
     // We use map() to extract the path, to use it as a test name in it.each()
     return inputs.map((data) => [data.filePath, data]);

tests/__mocks__/obsidian.ts

@@ -130,6 +130,13 @@ export function setCurrentCacheFile(mockData: any) {
     mockedFileData = mockData;
 }
 
+/**
+ * Fake implementation of Obsidian's `getAllTags()`.
+ *
+ * See https://docs.obsidian.md/Reference/TypeScript+API/getAllTags
+ *
+ * @param cachedMetadata
+ */
 export function getAllTags(cachedMetadata: CachedMetadata): string[] {
     if (cachedMetadata !== mockedFileData.cachedMetadata) {
         throw new Error(
@@ -139,6 +146,13 @@ export function getAllTags(cachedMetadata: CachedMetadata): string[] {
     return mockedFileData.getAllTags;
 }
 
+/**
+ * Fake implementation of Obsidian's `parseFrontMatterTags()`.
+ *
+ * See https://docs.obsidian.md/Reference/TypeScript+API/parseFrontMatterTags
+ *
+ * @param frontmatter
+ */
 export function parseFrontMatterTags(frontmatter: any | null): string[] | null {
     if (frontmatter !== mockedFileData.cachedMetadata.frontmatter) {
         throw new Error(