refactor: improve consistency in variable names, comments, and docs (#56)

* docs: teach JSDoc about the @typeparam tag from TSDoc

* test: provide mocks for obsidian-dataview types

* style: consistent type-replacement name

* style: sort members

* docs: improvements and additions

* style: keep comment next to code it's describing

* refactor: split constants out into their own file

* docs: fix broken type link

Author: brianrodri

eslint.config.js

@@ -16,7 +16,16 @@ export default defineConfig([
 
     { plugins: { js }, extends: ["js/recommended"] },
     { plugins: { jsdoc }, files: ["**/*.{js,jsx}"], extends: ["jsdoc/flat/recommended-error"] },
-    { plugins: { jsdoc }, files: ["**/*.{ts,tsx}"], extends: ["jsdoc/flat/recommended-typescript-error"] },
+    {
+        plugins: { jsdoc },
+        files: ["**/*.{ts,tsx}"],
+        extends: ["jsdoc/flat/recommended-typescript-error"],
+        settings: {
+            // Define the core TSDoc tag [`@typeParam`](https://tsdoc.org/pages/tags/typeparam/)
+            // See: https://github.com/gajus/eslint-plugin-jsdoc/issues/844#issuecomment-1051308663
+            jsdoc: { structuredTags: { typeParam: { name: "namepath-defining", type: false } } },
+        },
+    },
     { plugins: { tsdoc }, files: ["**/*.{ts,tsx}"], rules: { "tsdoc/syntax": "error" } },
 
     {

src/lib/obsidian-dataview/__mocks__/types.ts

@@ -0,0 +1,4 @@
+import { vi } from "vitest";
+
+export const getAPI = vi.fn();
+export const isPluginEnabled = vi.fn();

src/lib/obsidian-dataview/types.ts

@@ -1,13 +1,15 @@
 import { DateTime } from "luxon";
-import { DataArray } from "obsidian-dataview/lib/api/data-array";
+import type { DataArray } from "obsidian-dataview/lib/api/data-array";
 import type { DataviewApi as ActualDataviewApi } from "obsidian-dataview/lib/api/plugin-api";
 import type { SMarkdownPage, STask } from "obsidian-dataview/lib/data-model/serialized/markdown";
-import type { Link as DataviewLink } from "obsidian-dataview/lib/data-model/value";
+import type { Link as ActualLink } from "obsidian-dataview/lib/data-model/value";
 
 export { getAPI, isPluginEnabled } from "obsidian-dataview";
 
-/** The Obsidian 'link', used for uniquely describing a file, header, or block. Extended to improve type information. */
-export type Link = DataviewLink;
+/** The API that the obsidian-dataview plugin exposes to plugin authors. Extended to improve type information. */
+export declare class DataviewApi extends ActualDataviewApi {
+    override pages(query: string): DataArray<SMarkdownPage>;
+}
 
 /** The metadata that the obsidian-dataview plugin extracts from tasks. Extended to improve type information. */
 export interface DataviewMarkdownTask extends STask {
@@ -16,10 +18,8 @@ export interface DataviewMarkdownTask extends STask {
     completion?: DateTime;
     start?: DateTime;
     scheduled?: DateTime;
-    section: Link;
+    section: ActualLink;
 }
 
-/** The API that the obsidian-dataview plugin exposes to plugin authors. Extended to improve type information. */
-export interface DataviewApi extends ActualDataviewApi {
-    pages(query: string): DataArray<SMarkdownPage>;
-}
+/** The Obsidian 'link', used for uniquely describing a file, header, or block. Extended to improve type information. */
+export type Link = ActualLink;

src/model/collection/periodic-notes.ts

@@ -8,7 +8,10 @@ import { assertLuxonFormat, assertValid } from "@/util/luxon-utils";
 import { DateBasedCollection } from "./schema";
 import { sanitizeFolder } from "./util";
 
-/** Configuration options for {@link PeriodicNotes}. */
+/**
+ * Configuration options for {@link PeriodicNotes}.
+ * @param IsValidConfiguration - whether the configuration is valid.
+ */
 export type PeriodicNotesConfig<IsValidConfiguration extends boolean> =
     IsValidConfiguration extends true ?
         {
@@ -37,16 +40,12 @@ export type PeriodicNotesConfig<IsValidConfiguration extends boolean> =
         };
 
 /**
+ * Intended to handle the popular "Periodic Notes" community plugin.
+ * As a consequence, all files in the collection must be placed in the same folder.
  * @see {@link https://github.com/liamcain/obsidian-periodic-notes}
- *
- * A {@link DateBasedCollection} where each file corresponds to a unique {@link Interval} of time.
- * Intended to handle Obsidian's built-in "Daily Notes" plugin and the more-comprehensive "Periodic Notes" community
- * plugin. As a consequence, all files in the collection must be placed in the same folder.
- *
- * TODO: Is it worth supporting files organized into different folders?
  */
 export class PeriodicNotes extends DateBasedCollection implements PeriodicNotesConfig<true> {
-    /** The folder containing all of the notes. */
+    /** The folder containing all of the notes. TODO: Support files organized into different folders. */
     public readonly folder: string;
 
     /**
@@ -125,5 +124,6 @@ function validated(config: PeriodicNotesConfig<false>): PeriodicNotesConfig<true
         const indentedMessages = errors.map((error) => `${error.name}: ${error.message}`.replace(/^/gm, "\t"));
         throw new AggregateError(errors, ["invalid config", ...indentedMessages].join("\n"));
     }
+
     return { folder, dateFormat, dateOptions, intervalDuration, intervalOffset };
 }

src/model/collection/schema.ts

@@ -1,10 +1,6 @@
 import { IntervalMaybeValid } from "luxon";
 
-/**
- * Interface for Bullet Journal collections.
- *
- * Provides efficient functions for common operations required by views and other models.
- */
+/** Interface for Bullet Journal collections that provide efficient query functions. */
 export abstract class Collection {
     /**
      * @param filePath - the path to check.
@@ -13,11 +9,11 @@ export abstract class Collection {
     public abstract includes(filePath: string): boolean;
 }
 
+/** A {@link Collection} where each note corresponds to a unique {@link luxon.Interval} of time. */
 export abstract class DateBasedCollection extends Collection {
     /**
-     * Used to accurately enable date-based queries on collections and to look up "neighboring" files.
      * @param filePath - the path to check.
-     * @returns the valid interval corresponding to the file, otherwise an invalid interval.
+     * @returns the interval corresponding to the file, otherwise an invalid interval.
      */
     public abstract getIntervalOf(filePath: string): IntervalMaybeValid;
 

src/model/task/lib/obsidian-tasks.const.ts

@@ -0,0 +1,32 @@
+import { escapeRegExp, keysIn } from "lodash";
+import { PickByValue } from "utility-types";
+
+import { Task } from "@/model/task/schema";
+import { PathsOf } from "@/util/type-utils";
+
+export const SYMBOL_PATH_LOOKUP = {
+    "❌": "dates.cancelled",
+    "➕": "dates.created",
+    "✅": "dates.done",
+    "📅": "dates.due",
+    "⌛": "dates.scheduled",
+    "⏳": "dates.scheduled",
+    "🛫": "dates.start",
+    "⛔": "dependsOn",
+    "🆔": "id",
+    "🔺": "priority",
+    "⏫": "priority",
+    "🔼": "priority",
+    "🔽": "priority",
+    "⏬": "priority",
+} as const satisfies Record<string, PathsOf<Task>>;
+
+export const SYMBOL_PRIORITY_LOOKUP = {
+    "🔺": 0,
+    "⏫": 1,
+    "🔼": 2,
+    "🔽": 4,
+    "⏬": 5,
+} as const satisfies { [K in keyof PickByValue<typeof SYMBOL_PATH_LOOKUP, "priority">]: number };
+
+export const SYMBOL_REG_EXP = new RegExp(keysIn(SYMBOL_PATH_LOOKUP).map(escapeRegExp).join("|"), "g");

src/model/task/lib/obsidian-tasks.ts

@@ -1,9 +1,10 @@
-import { escapeRegExp, has, keysIn, set } from "lodash";
+import { has, set } from "lodash";
 import { DateTime } from "luxon";
-import { DeepPartial, PickByValue } from "utility-types";
+import { DeepPartial } from "utility-types";
 
 import { Task } from "@/model/task/schema";
-import { PathsOf } from "@/util/type-utils";
+
+import { SYMBOL_PATH_LOOKUP, SYMBOL_PRIORITY_LOOKUP, SYMBOL_REG_EXP } from "./obsidian-tasks.const";
 
 /**
  * Parses {@link Task} metadata from a real markdown blob using Obsidian Task's emoji format.
@@ -44,30 +45,3 @@ export function parseTaskEmojiFormat(text: string): DeepPartial<Task> {
 
     return result;
 }
-
-const SYMBOL_PATH_LOOKUP = {
-    "❌": "dates.cancelled",
-    "➕": "dates.created",
-    "✅": "dates.done",
-    "📅": "dates.due",
-    "⌛": "dates.scheduled",
-    "⏳": "dates.scheduled",
-    "🛫": "dates.start",
-    "⛔": "dependsOn",
-    "🆔": "id",
-    "🔺": "priority",
-    "⏫": "priority",
-    "🔼": "priority",
-    "🔽": "priority",
-    "⏬": "priority",
-} as const satisfies Record<string, PathsOf<Task>>;
-
-const SYMBOL_PRIORITY_LOOKUP = {
-    "🔺": 0,
-    "⏫": 1,
-    "🔼": 2,
-    "🔽": 4,
-    "⏬": 5,
-} as const satisfies { [K in keyof PickByValue<typeof SYMBOL_PATH_LOOKUP, "priority">]: number };
-
-const SYMBOL_REG_EXP = new RegExp(keysIn(SYMBOL_PATH_LOOKUP).map(escapeRegExp).join("|"), "g");

src/util/luxon-utils.ts

@@ -34,8 +34,7 @@ export function assertLuxonFormat(
     dateFormat: string,
     dateOptions?: DateTimeOptions,
 ): asserts dateFormat is LuxonFormat {
-    // NOTE: Any valid UTC date works.
-    const sourceDate = DateTime.fromMillis(0).setZone("utc");
+    const sourceDate = DateTime.fromMillis(0).setZone("utc"); // NOTE: Any valid UTC date works.
     const parsedDate = DateTime.fromFormat(sourceDate.toFormat(dateFormat, dateOptions), dateFormat, dateOptions);
     assert(
         parsedDate.isValid &&

src/util/type-utils.ts

@@ -1,5 +1,6 @@
 /**
  * The union of all dot-separated paths in an object rescursively.
+ * @typeParam T - the object to get paths from.
  * @example
  *
  * ```typescript