docs: reformat docs to stay consistent with how typedoc will render them

Author: brianrodri

src/model/collection/periodic-notes.ts

@@ -4,7 +4,7 @@ import { DateTime, DateTimeOptions, Duration, DurationLike, Interval, IntervalMa
 import { parse } from "path";
 import { DeepReadonly } from "utility-types";
 
-import { assertLuxonFormat, assertValid } from "@/util/luxon-utils";
+import { assertValidDateTimeFormat, assertValidLuxonValue } from "@/util/luxon-utils";
 
 import { DateBasedCollection } from "./schema";
 import { stripTrailingSlash } from "./util";
@@ -29,16 +29,13 @@ export class PeriodicNotes extends DateBasedCollection implements PeriodicNotesC
 
     /**
      * The {@link Duration} of each file's corresponding {@link Interval}.
-     * @example
-     * Daily notes should use a duration of `{ days: 1 }`.
+     * Daily notes, for example, should use a duration of `{ days: 1 }`.
      */
     public readonly intervalDuration: Duration<true>;
 
     /**
      * Offset between the file's _parsed_ date and the corresponding {@link Interval}'s _start_ date. May be negative.
-     * @example
-     * Sprint notes may use ISO weeks as their {@link dateFormat}, for example: `2025-W10.md`.
-     * If sprints _actually_ begin on Thursdays rather than Mondays, then we can adjust the interval with `{ days: 3 }`.
+     * Sprint notes, for example, can use ISO weeks for {@link dateFormat} and {@link intervalOffset} for their weekday.
      */
     public readonly intervalOffset: Duration<true>;
 
@@ -125,10 +122,10 @@ function validated(config: PeriodicNotesConfig<false>): PeriodicNotesConfig<true
 
     const errors = [
         attempt(() => assertNotStrictEqual(folder.length, 0, "folder must be non-empty")),
-        attempt(() => assertLuxonFormat(dateFormat, dateOptions)),
-        attempt(() => assertValid(intervalDuration, "interval duration is invalid")),
+        attempt(() => assertValidDateTimeFormat(dateFormat, dateOptions)),
+        attempt(() => assertValidLuxonValue(intervalDuration, "interval duration is invalid")),
         attempt(() => assertNotStrictEqual(intervalDuration.valueOf(), 0, "interval duration must not be zero")),
-        attempt(() => assertValid(intervalOffset, "interval offset is invalid")),
+        attempt(() => assertValidLuxonValue(intervalOffset, "interval offset is invalid")),
     ].filter(isError);
 
     if (errors.length > 0) {

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

@@ -8,15 +8,18 @@ import { SYMBOL_PATH_LOOKUP, SYMBOL_PRIORITY_LOOKUP, SYMBOL_REG_EXP } from "./ob
 
 /**
  * Parses {@link Task} metadata from a real markdown blob using Obsidian Task's emoji format.
+ *
+ * Here's an illustration:
+ * ```
+ * //                                                                      ( 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" }
+ * ```
  * @param text - the text of the task without its' markdown text.
  * @returns a {@link Task} with the parsed metadata.
  * @see {@link https://publish.obsidian.md/tasks/Reference/Task+Formats/Tasks+Emoji+Format}
- * @example
- *                                                                         ( 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" \}
  */
 export function parseTaskEmojiFormat(text: string): DeepPartial<Task> {
     const matchedSymbols = [...text.matchAll(SYMBOL_REG_EXP), /$/.exec(text) as RegExpExecArray];

src/util/__tests__/luxon-utils.test.ts

@@ -1,9 +1,9 @@
 import { DateTime, Duration, Interval } from "luxon";
 import { describe, expect, it } from "vitest";
 
-import { assertLuxonFormat, assertValid } from "../luxon-utils";
+import { assertValidDateTimeFormat, assertValidLuxonValue } from "../luxon-utils";
 
-describe(`${assertValid.name}`, () => {
+describe(`${assertValidLuxonValue.name}`, () => {
     const reason = "user-provided reason";
     const explanation = "user-provided explanation";
 
@@ -13,24 +13,24 @@ describe(`${assertValid.name}`, () => {
             Duration.fromDurationLike({ days: 1 }),
             Interval.after(DateTime.now(), { days: 1 }),
         ])("should accept valid $constructor.name", (value) => {
-            expect(() => assertValid(value, message)).not.toThrow();
+            expect(() => assertValidLuxonValue(value, message)).not.toThrow();
         });
 
         it.each([DateTime.fromISO("2025-03-99"), Duration.invalid(reason), Interval.invalid(reason, explanation)])(
             "should reject invalid $constructor.name",
             (value) => {
-                expect(() => assertValid(value, message)).toThrowErrorMatchingSnapshot();
+                expect(() => assertValidLuxonValue(value, message)).toThrowErrorMatchingSnapshot();
             },
         );
     });
 });
 
-describe(`${assertLuxonFormat.name}`, () => {
+describe(`${assertValidDateTimeFormat.name}`, () => {
     it.each(["yyyy-MM-dd", "kkkk-'W'WW", "yyyy-MM"])("should accept valid format=%j", (validFormat) => {
-        expect(() => assertLuxonFormat(validFormat)).not.toThrow();
+        expect(() => assertValidDateTimeFormat(validFormat)).not.toThrow();
     });
 
     it.each(["FF", "''"])("should reject invalid format=%j", (invalidFormat) => {
-        expect(() => assertLuxonFormat(invalidFormat)).toThrowErrorMatchingSnapshot();
+        expect(() => assertValidDateTimeFormat(invalidFormat)).toThrowErrorMatchingSnapshot();
     });
 });

src/util/luxon-utils.ts

@@ -18,22 +18,21 @@ export type LuxonFormat = Brand<string, "LuxonFormat">;
  * @param message - Optional custom header for the error message.
  * @throws If the provided value is invalid.
  */
-export function assertValid(
+export function assertValidLuxonValue(
     value: LuxonValue<true> | LuxonValue<false>,
     message?: string,
 ): asserts value is LuxonValue<true> {
-    const { invalidReason, invalidExplanation } = value;
-    const header = message ?? `Invalid ${value.constructor.name}`;
-    const reason = invalidExplanation ? `${invalidReason}: ${invalidExplanation}` : invalidReason;
-    assert(value.isValid, `${header}: ${reason}`);
+    message ??= `Invalid ${value.constructor.name}`;
+    const help = value.invalidExplanation ? `${value.invalidReason}: ${value.invalidExplanation}` : value.invalidReason;
+    assert(value.isValid, `${message}: ${help}`);
 }
 
 /**
  * @param dateFormat - the format to check.
  * @param dateOptions - the options to use when parsing and formatting.
  * @see {@link https://moment.github.io/luxon/#/parsing?id=table-of-tokens}
  */
-export function assertLuxonFormat(
+export function assertValidDateTimeFormat(
     dateFormat: string,
     dateOptions?: DateTimeOptions,
 ): asserts dateFormat is LuxonFormat {

src/util/type-utils.ts

@@ -1,14 +1,14 @@
 /**
  * The union of all dot-separated paths in an object rescursively.
- * @typeParam T - the object to get paths from.
- * @example
  *
+ * Here's an illustration:
  * ```typescript
  * type Obj = { a: { b: { c: string } } };
  *
  * type ObjPaths = PathsOf<Obj>;
  * //   ^? type ObjPaths = "a" | "a.b" | "a.b.c"
  * ```
+ * @typeParam T - the object to get paths from.
  */
 export type PathsOf<T> =
     T extends object ?