docs: fully document the code base (#28)

* refactor: move const definitions into a dedicated .const.ts file

* docs: fix broken links

* chore: remove recurrence rules until ready to implement

* docs: fully document all classes

* build: disable JSDoc lint checks in TypeScript files; rely on TSDoc instead

* Apply suggestions from code review

* chore: remove scheduled times until ready to implement

* docs: enforce documentation on .const.ts files

* docs: fix links and improve TSDoc contents

* Apply suggestions from code review

Author: brianrodri

boundaries.config.js

@@ -34,7 +34,7 @@ export const ELEMENT_TYPE_RULES = [
     { from: "*", allow: "shared" },
     { from: "main", allow: [["lib", { lib: "obsidian" }]] },
     { from: "(lib|lib:scope)", allow: [["lib", { lib: "${from.lib}" }]] },
-    { from: "const", disallow: "*" },
+    { from: "const", allow: "./*" },
 
     ...fromScopeAllowItself("model"),
     ...fromScopeElementAllowTargetScopeElements("model", "index", [["model", "collection"]]),

eslint.config.js

@@ -38,14 +38,12 @@ export default [
         files: ["src/**/*.{ts,tsx}"],
         plugins: {
             "@typescript-eslint": typescriptEslintPlugin,
-            "jsdoc": eslintPluginJsdoc,
             "react-hooks": eslintPluginReactHooks,
             "tsdoc": eslintPluginTsdoc,
         },
         rules: {
             ...typescriptEslintPlugin.configs.recommended.rules,
             ...typescriptEslintPlugin.configs.strict.rules,
-            ...eslintPluginJsdoc.configs["flat/recommended-typescript-error"].rules,
             ...eslintPluginReactHooks.configs.recommended.rules,
 
             // https://tsdoc.org/pages/packages/eslint-plugin-tsdoc/

package-lock.json

@@ -71,6 +71,7 @@
         "typedoc": "^0.27.9",
         "typedoc-github-theme": "^0.2.1",
         "typedoc-plugin-coverage": "^3.4.1",
+        "typedoc-plugin-dt-links": "^1.1.14",
         "typescript": "^5.8.2",
         "utility-types": "^3.11.0",
         "vite": "^6.2.0",

package.json

@@ -5,8 +5,10 @@ import type { SMarkdownPage, STask } from "obsidian-dataview/lib/data-model/seri
 
 export { getAPI, isPluginEnabled } from "obsidian-dataview";
 
+/** Metadata the obsidian-dataview plugin tracks from notes. */
 export type DataviewMarkdownPage = SMarkdownPage;
 
+/** Metadata the obsidian-dataview plugin tracks from tasks. Extended to improve type information. */
 export interface DataviewMarkdownTask extends STask {
     created?: DateTime;
     due?: DateTime;
@@ -15,6 +17,7 @@ export interface DataviewMarkdownTask extends STask {
     scheduled?: DateTime;
 }
 
+/** API the obsidian-dataview plugin exposes to plugin authors. Extended to improve type information. */
 export interface DataviewApi extends ActualDataviewApi {
     pages(query: string): DataArray<SMarkdownPage>;
 }

src/lib/obsidian-dataview/types.ts

@@ -1,8 +1,10 @@
 import { Plugin } from "@/lib/obsidian/types";
 
+/** Entry point for the plugin. Obsidian depends on this class to define all lifecycle events and rendering behavior. */
 export class Objo extends Plugin {
+    /** Called by Obsidian to give the plugin an opportunity to "load" and hook into the ecosystem. */
     override onload() {
-        this.app.workspace.onLayoutReady(() => console.log("started"));
+        this.app.workspace.onLayoutReady(() => console.log("loaded"));
     }
 }
 

src/main.tsx

@@ -4,11 +4,39 @@ import { parse } from "path";
 
 import { Collection } from "./schema";
 
+/**
+ * Represents a collection of files, each corresponding to unique {@link Interval} of time, kept inside the same folder.
+ * Intended to handle Obsidian's built-in "Daily Log" plugin and the more-comprehensive "Periodic log" community plugin.
+ */
 export class PeriodicLog extends Collection {
+    /**
+     * The folder containing all of the notes.
+     * TODO: Is it worth supporting files organized into different folders?
+     */
     public readonly folder: string;
+
+    /**
+     * Luxon format used to parse dates from the file's name.
+     * @see {@link https://moment.github.io/luxon/#/parsing?id=table-of-tokens}
+     */
     public readonly dateFormat: string;
+
+    /**
+     * Offset between the file's _parsed_ date and the corresponding {@link Interval}'s _start_ date. May be negative.
+     *
+     * @example a periodic sprint log using ISO weeks, which start on Monday, as its {@link dateFormat} when sprints
+     * _actually_ begin on Thursdays.
+     */
     public readonly dateOffset: Duration<true>;
+
+    /**
+     * The {@link Duration} of each file's corresponding {@link Interval}.
+     *
+     * @example a daily log's duration would be `{ days: 1 }`.
+     */
     public readonly intervalDuration: Duration<true>;
+
+    /** Luxon options used when parsing {@link DateTime}s from file names. */
     public readonly dateOptions: DateTimeOptions;
 
     public constructor(
@@ -36,10 +64,12 @@ export class PeriodicLog extends Collection {
         this.dateOptions = dateOptions;
     }
 
+    /** {@inheritDoc model/collection/schema.Collection#includes} */
     public override includes(filePath: string): boolean {
         return this.getIntervalOf(filePath).isValid;
     }
 
+    /** {@inheritDoc model/collection/schema.Collection#getIntervalOf} */
     public override getIntervalOf(filePath: string): IntervalMaybeValid {
         const path = parse(filePath);
         if (path.dir !== this.folder) {

src/model/collection/periodic-log.ts

@@ -1,8 +1,23 @@
 import { Interval, IntervalMaybeValid } from "luxon";
 
+/**
+ * Interface for Bullet Journal collections.
+ *
+ * Provides efficient functions for common operations required by views and other models.
+ */
 export abstract class Collection {
+    /**
+     * @param filePath - the path to check.
+     * @returns whether the file at the given path belongs to this collection.
+     */
     public abstract includes(filePath: string): boolean;
-    // TODO: Would this make more sense in its own interface?
+
+    /**
+     * @param filePath - the path to check.
+     * @returns the {@link Interval} corresponding to the file, otherwise an invalid interval.
+     *
+     * Used to accurately enable date-based queries on collections and to look up "neighboring" files.
+     */
     public getIntervalOf(filePath: string): IntervalMaybeValid {
         return Interval.invalid(`interval not implemented`, `"${filePath}" was ignored`);
     }

src/model/collection/schema.ts

@@ -9,6 +9,7 @@ export interface VaultIndex {
      * Register a new {@link Collection} into the index.
      * All calls to this function will be treated as adding a brand new collection, regardless
      * of whether the input has already been registered in an earlier call.
+     *
      * @param collection - the collection to register with this index.
      * @throws if the index cannot support the given collection.
      * @returns a {@link VaultCollectionIndex} that can be used to interact with the primary index.

src/model/index/schema.ts

@@ -13,10 +13,7 @@ describe("Parsing task emojis", () => {
         [{ priority: 2 }, "🔼"],
         [{ priority: 4 }, "🔽"],
         [{ priority: 5 }, "⏬"],
-        [{ recurrenceRule: "every day" }, "🔁 every day"],
         [{ id: "due3rd", dependsOn: new Set(["due1st", "due2nd"]) }, "🆔 due3rd ⛔ due1st, due2nd"],
-        [{ times: { start: isoDateTime("09:00") } }, "09:00 do at 9am"],
-        [{ times: { start: isoDateTime("09:00"), end: isoDateTime("10:00") } }, "09:00/10:00 do between 9am and 10am"],
         [{ dates: { cancelled: isoDateTime("2024-10-25") } }, "❌ 2024-10-25"],
         [{ dates: { created: isoDateTime("2024-10-26") } }, "➕ 2024-10-26"],
         [{ dates: { done: isoDateTime("2024-10-27") } }, "✅ 2024-10-27"],
@@ -35,14 +32,13 @@ describe("Parsing task emojis", () => {
     it("parses sequential fields", () => {
         expect(
             parseTaskEmojiFormat(`
-                09:00/10:00 TODO! 🔺 🔁 every day 🆔 do3rd ⛔ do1st, do2nd
+                TODO! 🔺 🆔 do3rd ⛔ do1st, do2nd
                     ❌ 2024-10-25 ➕ 2024-10-26 ✅ 2024-10-27
                     📅 2024-10-28 ⏳ 2024-10-29 🛫 2024-10-30
             `),
         ).toEqual({
             description: "TODO!",
             priority: 0,
-            recurrenceRule: "every day",
             id: "do3rd",
             dependsOn: new Set(["do1st", "do2nd"]),
             dates: {
@@ -53,10 +49,6 @@ describe("Parsing task emojis", () => {
                 scheduled: isoDateTime("2024-10-29"),
                 start: isoDateTime("2024-10-30"),
             },
-            times: {
-                start: isoDateTime("09:00"),
-                end: isoDateTime("10:00"),
-            },
         });
     });
 });

src/model/task/constants.ts

@@ -5,7 +5,7 @@ import { Task } from "@/model/task/schema";
 
 /**
  * @param task - the {@link DataviewMarkdownTask} to extract metadata from.
- * @returns a {@link Task} with the extracted metadata.
+ * @returns a {@link Task} with the extracted metadata and default vaules everywhere else.
  */
 export function adaptDataviewMarkdownTask(task: DataviewMarkdownTask): DeepPartial<Task> {
     return {

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

@@ -1,28 +1,32 @@
 import { escapeRegExp, has, keysIn, set } from "lodash";
-import { DateTime, Interval } from "luxon";
+import { DateTime } from "luxon";
 import { DeepPartial, PickByValue } from "utility-types";
 
 import { Task } from "@/model/task/schema";
-import { PathOf } from "@/util/type-utils";
+import { PathsOf } from "@/util/type-utils";
 
 /**
- * Parses {@link Task} metadata from a real markdown task using the Obsidian Task plugin's syntax.
- * Specifically, the text is expected to find occurrences from the {@link SYMBOL_PATH_LOOKUP} and write to the
- * corresponding field using the proceeding text.
+ * Parses {@link Task} metadata from a real markdown blob using Obsidian Task's emoji format.
+ *
+ * @see {@link https://publish.obsidian.md/tasks/Reference/Task+Formats/Tasks+Emoji+Format}
  * @example
+ *
  * ```
- * "the text at the front is assumed to be a description. ❌ cancelled date ➕ created date ✅ completed date"
- *                                                       ( symbol & value )(symbol & value)( symbol & value  )
+ *                                                                         ( symbol & value )
+ * "the text at the front is assumed to be a description. ❌ cancelled date ➕ creation date ✅ completed date"
+ *                                                       ( symbol & value )                 ( symbol & value  )
+ *
+ * { cancelled: "cancelled date", created: "creation date", done: "completed date" }
  * ```
- * @see {@link https://publish.obsidian.md/tasks/Reference/Task+Formats/Tasks+Emoji+Format}
+ *
  * @param text - the text of the task without its' markdown text.
  * @returns a {@link Task} with the parsed metadata.
  */
 export function parseTaskEmojiFormat(text: string): DeepPartial<Task> {
     const matchedSymbols = [...text.matchAll(SYMBOL_REG_EXP), /$/.exec(text) as RegExpExecArray];
     const textBeforeAllSymbols = text.slice(0, matchedSymbols[0].index);
 
-    const result: DeepPartial<Task> = { ...parseTaskHeader(textBeforeAllSymbols.trim()) };
+    const result: DeepPartial<Task> = { description: textBeforeAllSymbols.trim() };
 
     for (let i = 0; i <= matchedSymbols.length - 2; ++i) {
         const [execArray, nextExecArray] = matchedSymbols.slice(i, i + 2);
@@ -46,27 +50,6 @@ export function parseTaskEmojiFormat(text: string): DeepPartial<Task> {
     return result;
 }
 
-/**
- * Parses {@link Task} metadata from a task's header.
- * @param headerText - the text that appears _before_ all of the symbols.
- * @returns the {@link Task} metadata fields parsed from the header; unparsed data will become {@link Task.description}.
- */
-function parseTaskHeader(headerText: string): DeepPartial<Task> {
-    const [isoString, isoStringSuffix] = headerText.split(/\s+/, 2);
-
-    const interval = Interval.fromISO(isoString);
-    if (interval.isValid) {
-        return { times: { start: interval.start, end: interval.end }, description: isoStringSuffix };
-    }
-
-    const time = DateTime.fromISO(isoString);
-    if (time.isValid) {
-        return { times: { start: time }, description: isoStringSuffix };
-    }
-
-    return { description: headerText };
-}
-
 const SYMBOL_PATH_LOOKUP = {
     "❌": "dates.cancelled",
     "➕": "dates.created",
@@ -82,15 +65,14 @@ const SYMBOL_PATH_LOOKUP = {
     "🔼": "priority",
     "🔽": "priority",
     "⏬": "priority",
-    "🔁": "recurrenceRule",
-} as const satisfies Record<string, PathOf<Task>>;
+} as const satisfies Record<string, PathsOf<Task>>;
 
 const SYMBOL_PRIORITY_LOOKUP = {
     "🔺": 0,
     "⏫": 1,
     "🔼": 2,
     "🔽": 4,
     "⏬": 5,
-} as const satisfies Record<keyof PickByValue<typeof SYMBOL_PATH_LOOKUP, "priority">, number>;
+} 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/model/task/lib/obsidian-dataview.ts

@@ -0,0 +1,34 @@
+import { DateTime } from "luxon";
+
+import { Task, TaskSource, TaskStatus } from "./schema";
+
+/** The default date used by {@link Task}s. Valid dates will always take precedence over invalid dates. */
+export const DEFAULT_DATETIME_VALUE: DateTime = DateTime.invalid("unspecified");
+
+/** The default priority used by {@link Task}s. Different values will always take precedence over this value. */
+export const DEFAULT_PRIORITY_VALUE: Task["priority"] = 3;
+
+/**
+ * The default type used by {@link TaskSource} and {@link TaskStatus}.
+ * Different values will always take precedence over this value.
+ */
+export const DEFAULT_TYPE_VALUE: TaskSource["type"] & TaskStatus["type"] = "UNKNOWN";
+
+/** A strongly-typed {@link Task} with all-default values. */
+export const TASK_WITH_DEFAULT_VALUES: Task = {
+    status: { type: DEFAULT_TYPE_VALUE },
+    source: { type: DEFAULT_TYPE_VALUE },
+    dates: {
+        cancelled: DEFAULT_DATETIME_VALUE,
+        created: DEFAULT_DATETIME_VALUE,
+        done: DEFAULT_DATETIME_VALUE,
+        due: DEFAULT_DATETIME_VALUE,
+        scheduled: DEFAULT_DATETIME_VALUE,
+        start: DEFAULT_DATETIME_VALUE,
+    },
+    description: "",
+    priority: DEFAULT_PRIORITY_VALUE,
+    tags: new Set(),
+    id: "",
+    dependsOn: new Set(),
+};