📝 Add docstrings to docs

Docstrings generation was requested by @brianrodri.

* #57 (comment)

The following files were modified:

* `src/model/collection/periodic-notes.ts`
* `src/model/collection/util.ts`
* `src/model/task/util.ts`
* `src/util/luxon-utils.ts`

Author: coderabbitai[bot]

src/model/collection/periodic-notes.ts

@@ -102,9 +102,21 @@ export type PeriodicNotesConfig<IsValidConfiguration extends boolean> =
         };
 
 /**
- * @param config - the config to validate.
- * @throws if any of the config's properties are invalid.
- * @returns a new valid config with narrower types.
+ * Validates a PeriodicNotes configuration object.
+ *
+ * This function ensures that:
+ * - The folder path, after removing any trailing slash, is non-empty.
+ * - The date format is valid with the provided date options.
+ * - The interval duration is a valid, non-zero duration.
+ * - The interval offset is a valid duration.
+ *
+ * If any of these validations fail, an {@link AggregateError} is thrown detailing all issues.
+ * Otherwise, it returns a new configuration object with more specific types.
+ *
+ * @param config - The configuration object to validate.
+ * @returns A validated configuration with strictly defined properties.
+ *
+ * @throws {AggregateError} If one or more properties of the configuration are invalid.
  */
 function validated(config: PeriodicNotesConfig<false>): PeriodicNotesConfig<true> {
     const folder = stripTrailingSlash(config.folder);

src/model/collection/util.ts

@@ -1,6 +1,10 @@
 /**
- * @param folder - the folder to sanitize.
- * @returns sanitized value with trailing slashes removed, if applicable.
+ * Returns a sanitized folder path by removing a trailing slash unless the path is the root ("/").
+ *
+ * The function trims whitespace from the input folder string. If the trimmed string equals "/", it is returned unchanged. Otherwise, any trailing slash is removed.
+ *
+ * @param folder - The folder path to sanitize.
+ * @returns The folder path without a trailing slash, except for the root path.
  */
 export function stripTrailingSlash(folder: string): string {
     folder = folder.trim();

src/model/task/util.ts

@@ -5,7 +5,11 @@ import { DeepPartial } from "utility-types";
 import { DEFAULT_PRIORITY_VALUE, DEFAULT_TYPE_VALUE, Task, TASK_WITH_DEFAULT_VALUES } from "@/model/task/schema";
 
 /**
- * @param parts - the task parts to merge.
+ * Merges multiple partial Task objects into a complete Task using a custom merge strategy.
+ *
+ * The function begins with default Task values and sequentially merges each provided partial Task. For each property, the front-most non-default value is retained. Special handling is applied for properties such as task type, priority, strings, DateTime objects, and Set collections.
+ *
+ * @param parts - The partial Task objects to merge.
  * @returns new {@link Task} with the front-most non-default values taken from the parts.
  */
 export function mergeTaskParts(...parts: DeepPartial<Task>[]): Task {

src/util/luxon-utils.ts

@@ -9,9 +9,16 @@ export type LuxonValue<IsValid extends boolean> = DateTime<IsValid> | Duration<I
 export type LuxonFormat = Brand<string, "LuxonFormat">;
 
 /**
- * @param value - the {@link LuxonValue} to check.
- * @param message - the message to use in the error.
- * @throws error if value is invalid.
+ * Asserts that the provided Luxon value is valid.
+ *
+ * This function checks whether a Luxon date, duration, or interval is valid. If the value is invalid,
+ * it throws an error with a message combining a custom header (or default constructor name) with the
+ * value's invalid reason and, if available, its invalid explanation.
+ *
+ * @param value - The Luxon object to validate.
+ * @param message - Optional custom header for the error message.
+ *
+ * @throws {Error} If the provided value is invalid.
  */
 export function assertValid(
     value: LuxonValue<true> | LuxonValue<false>,