docs: install eslint-plugin-jsdoc and fix all errors (#27)

Author: brianrodri

boundaries.config.js

@@ -3,6 +3,7 @@ const libDir = "lib";
 // EXPORTS
 ////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////
 
+/** @see {@link https://github.com/javierbrea/eslint-plugin-boundaries#rules-configuration} */
 export const ELEMENTS = [
     { type: "shared", pattern: "src/util", mode: "folder" },
     { type: "main", pattern: "src/main.tsx", mode: "full" },
@@ -28,6 +29,7 @@ export const ELEMENTS = [
     defineFolderScope("model"),
 ];
 
+/** @see {@link https://github.com/javierbrea/eslint-plugin-boundaries#rules-configuration} */
 export const ELEMENT_TYPE_RULES = [
     { from: "*", allow: "shared" },
     { from: "main", allow: [["lib", { lib: "obsidian" }]] },
@@ -38,18 +40,25 @@ export const ELEMENT_TYPE_RULES = [
     ...fromScopeElementAllowTargetScopeElements("model", "index", [["model", "collection"]]),
 ];
 
+/** @see {@link https://github.com/javierbrea/eslint-plugin-boundaries#rules-configuration} */
 export const EXTERNAL_RULES = [
     { from: "*", allow: ["aggregate-error", "assert", "lodash", "luxon", "path", "utility-types"] },
     { from: "lib", allow: "${from.lib}" },
 ];
 
-// HELPERS
-////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////
-
+/**
+ * Defines a "scope" of code, or a folder that needs explicit permission to import from anywhere else.
+ * @param {string} folderName - the name of the folder and, consequently, the scope.
+ * @returns {object} the eslint-plugin-boundaries rule that will define the scope as its own type.
+ */
 function defineFolderScope(folderName) {
     return { type: folderName, pattern: `src/(${folderName})/*`, capture: ["scope", "elementName"], mode: "folder" };
 }
 
+/**
+ * @param {string} scope - the name of the scope.
+ * @returns {Array} the set of rules that will allow "scopes" to import from code in the same folder.
+ */
 function fromScopeAllowItself(scope) {
     return [
         {
@@ -59,6 +68,12 @@ function fromScopeAllowItself(scope) {
     ];
 }
 
+/**
+ * @param {string} fromScope - the scope where imports will be allowed from.
+ * @param {string} fromElementName - the name of the scope-element (i.e., "src/model/task" -> "task").
+ * @param {Array} targets - the list of scope/name pairs to allow imports from.
+ * @returns {Array} the set of rules that will allow "scopes" to import from code in the same folder.
+ */
 function fromScopeElementAllowTargetScopeElements(fromScope, fromElementName, targets) {
     return [
         {

eslint.config.js

@@ -6,34 +6,49 @@ import eslintPluginReactHooks from "eslint-plugin-react-hooks";
 import globals from "globals";
 import typescriptEslintParser from "@typescript-eslint/parser";
 import typescriptEslintPlugin from "@typescript-eslint/eslint-plugin";
+import eslintPluginJsdoc from "eslint-plugin-jsdoc";
 import eslintPluginTsdoc from "eslint-plugin-tsdoc";
 import { ELEMENTS, ELEMENT_TYPE_RULES, EXTERNAL_RULES } from "./boundaries.config.js";
+import eslintJs from "@eslint/js";
 
 /** @type { import("eslint").Linter.Config[] } */
 export default [
     { ignores: [".husky/", "coverage/", "docs/", "dist/", "node_modules/"] },
 
+    eslintJs.configs.recommended,
     eslintPluginImport.flatConfigs.recommended,
     ...eslintConfigPreact.flat,
 
     {
         files: ["*.config.js"],
-        rules: { "import/no-named-as-default": "off", "import/no-unresolved": "off" },
+        plugins: { jsdoc: eslintPluginJsdoc },
         languageOptions: { globals: { ...globals.node } },
+        ...eslintPluginJsdoc.configs["flat/recommended-error"],
+        rules: {
+            ...eslintPluginJsdoc.configs["flat/recommended-error"].rules,
+            "import/no-named-as-default": "off",
+            "import/no-unresolved": "off",
+        },
+        settings: {
+            "import/core-modules": ["eslint-config-preact", "eslint-plugin-boundaries", "eslint-plugin-import"],
+        },
     },
 
     {
         files: ["src/**/*.{ts,tsx}"],
         plugins: {
-            "tsdoc": eslintPluginTsdoc,
             "@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/
             "tsdoc/syntax": "error",
 
             // TypeScript already checks for duplicates: https://archive.eslint.org/docs/rules/no-dupe-class-members
@@ -52,6 +67,9 @@ export default [
             "import/no-named-as-default-member": "error",
             "import/no-duplicates": "error",
         },
+        settings: {
+            "import/core-modules": ["obsidian"],
+        },
         languageOptions: {
             globals: { ...globals.browser },
             parser: typescriptEslintParser,

package-lock.json

@@ -55,6 +55,7 @@
         "eslint-plugin-boundaries": "^5.0.1",
         "eslint-plugin-compat": "^6.0.2",
         "eslint-plugin-import": "^2.31.0",
+        "eslint-plugin-jsdoc": "^50.6.3",
         "eslint-plugin-prettier": "^5.2.3",
         "eslint-plugin-react": "^7.37.4",
         "eslint-plugin-react-hooks": "^5.2.0",

package.json

@@ -7,10 +7,8 @@ import { Collection } from "../collection/schema";
 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

@@ -3,6 +3,10 @@ import { DeepPartial } from "utility-types";
 import { DataviewMarkdownTask } from "@/lib/obsidian-dataview/types";
 import { Task } from "@/model/task/schema";
 
+/**
+ * @param task - the {@link DataviewMarkdownTask} to extract metadata from.
+ * @returns a {@link Task} with the extracted metadata.
+ */
 export function adaptDataviewMarkdownTask(task: DataviewMarkdownTask): DeepPartial<Task> {
     return {
         status: {

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

@@ -5,6 +5,19 @@ import { DeepPartial, PickByValue } from "utility-types";
 import { Task } from "@/model/task/schema";
 import { PathOf } 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.
+ * @example
+ * ```
+ * "the text at the front is assumed to be a description. ❌ cancelled date ➕ created date ✅ completed date"
+ *                                                       ( symbol & value )(symbol & value)( symbol & value  )
+ * ```
+ * @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);
@@ -33,6 +46,11 @@ 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);
 

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

@@ -5,10 +5,21 @@ import { DeepPartial } from "utility-types";
 import { DEFAULT_PRIORITY_VALUE, DEFAULT_TYPE_VALUE, TASK_WITH_DEFAULT_VALUES } from "@/model/task/constants";
 import { Task } from "@/model/task/schema";
 
+/**
+ * @param parts - the task pieces to merge.
+ * @returns a new {@link Task} with values taken from the front-most non-default {@link parts} encountered.
+ * @see {@link TASK_WITH_DEFAULT_VALUES}
+ */
 export function mergeTaskParts(...parts: DeepPartial<Task>[]): Task {
     return parts.reduce(replaceDefaultValues, { ...TASK_WITH_DEFAULT_VALUES });
 }
 
+/**
+ * Replaces any default values in {@link task} with non-default values from {@link part}.
+ * @param task - the task to modify.
+ * @param part - the task piece to take from.
+ * @returns the modified {@link Task}.
+ */
 function replaceDefaultValues(task: Task, part: DeepPartial<Task>): Task {
     return _.mergeWith(task, part, (oldValue, newValue, propName) => {
         if (propName === "type" && _.isString(oldValue) && _.isString(newValue)) {