From f5d8346eccae50d719e4db6804beb818e67beed8 Mon Sep 17 00:00:00 2001
From: Max <maximogarciamtnez@gmail.com>
Date: Wed, 3 Apr 2024 22:40:02 +0200
Subject: [PATCH] docs: add jsdocs for main exports (#55)

---
 src/_parse.ts    | 42 ++++++++++++++++++++++++++++++++++++++++++
 src/automd.ts    | 34 ++++++++++++++++++++++++++++++++--
 src/config.ts    | 12 ++++++------
 src/generator.ts | 14 ++++++++++++++
 src/transform.ts | 39 ++++++++++++++++++++++++++++++++++++++-
 5 files changed, 132 insertions(+), 9 deletions(-)

diff --git a/src/_parse.ts b/src/_parse.ts
index 30a7b67..c5cbd8a 100644
--- a/src/_parse.ts
+++ b/src/_parse.ts
@@ -2,13 +2,38 @@ import { destr } from "destr";
 import { camelCase } from "scule";
 
 export interface Block {
+  /**
+   * The name of the generator to use for updates.
+   */
   generator: string;
+
+  /**
+   * The arguments that are passed to the generator.
+   */
   rawArgs: string;
+
+  /**
+   * The current content of the block.
+   */
   contents: string;
+
+  /**
+   * The location of the content in the original document.
+   */
   loc: { start: number; end: number };
+
+  /**
+   * The location including the automd comments.
+   */
   _loc: { start: number; end: number };
 }
 
+/**
+ * Searches a markdown document for special sections that `automd` can update.
+ * 
+ * @param md - The markdown document as a string.
+ * @returns an array of blocks that can be updated automatically. {@link Block}
+ */
 export function findBlocks(md: string): Block[] {
   const blocks: Block[] = [];
 
@@ -36,10 +61,27 @@ export function findBlocks(md: string): Block[] {
   return blocks;
 }
 
+/**
+ * Checks if a markdown document contains sections that can be automatically updated.
+ * 
+ * @param md - The markdown document as a string.
+ * @returns true if there are `automd` sections, false otherwise.
+ */
 export function containsAutomd(md: string) {
   return /^<!--\s*automd:/gimsu.test(md);
 }
 
+/**
+ * Converts a string of raw arguments to an object.
+ * Each argument is separated by spaces. Arguments can be key-value pairs separated by '='.
+ * If an argument starts with "no-", the key is set to false. 
+ * Otherwise it sets the key to true. Keys are converted to camelCase.
+ * Values are processed to determine their actual type (e.g. string, boolean).
+ * 
+ * @param {string} rawArgs - The string of arguments to parse.
+ * @return {Object} - An object with keys derived from the arguments. 
+ * Keys are in camelCase. Values are true, false, or strings.
+ */
 export function parseRawArgs(rawArgs: string) {
   const args = Object.create(null);
 
diff --git a/src/automd.ts b/src/automd.ts
index 91a023c..ce80def 100644
--- a/src/automd.ts
+++ b/src/automd.ts
@@ -12,12 +12,42 @@ export interface AutomdResult extends TransformResult {
   output: string;
 }
 
-export async function automd(_config: Config = {}): Promise<{
+/**
+ * Describes what you get back from the `automd` function.
+ */
+export interface AutomdReturn {
+  /**
+   * A list of the changes made to the file(s) by `automd`.
+   */
   results: AutomdResult[];
+
+  /**
+   * How long it took to make the changes, in milliseconds.
+   */
   time: number;
+
+  /**
+   * The resolved configuration that were used for these changes.
+   */
   config: ResolvedConfig;
+
+  /**
+   * If you started watching the file(s) for changes, this function can be called to stop watching.
+   */
   unwatch?: () => void | Promise<void>;
-}> {
+}
+
+/**
+ * Scans a markdown file looking for special comments. 
+ * These comments tell the function to add or update certain parts of the file automatically.
+ * You can change how this works by giving it different settings in the `_config` option.
+ * 
+ * @param _config - The settings to use for the update process. See {@link Config}.
+ * @returns - An object containing the results of the update, including any changes made and any problems found. See {@link AutomdReturn}.
+ * 
+ * @see https://automd.unjs.io/guide
+ */
+export async function automd(_config: Config = {}): Promise<AutomdReturn> {
   const start = performance.now();
   const config = await loadConfig(_config.dir, _config);
 
diff --git a/src/config.ts b/src/config.ts
index 0707466..af5e59a 100644
--- a/src/config.ts
+++ b/src/config.ts
@@ -4,30 +4,30 @@ import type { AutomdResult } from "./automd";
 
 export interface Config {
   /**
-   * Working directory
+   * The working directory
    *
-   * Defaults to the current working directory
+   * @default "." (current directory)
    */
   dir?: string;
 
   /**
    * Name or path to the input file or files with glob patterns.
    *
-   * Default is `README.md`.
+   * @default "README.md"
    */
   input?: string | string[];
 
   /**
-   * Name or path of the output files.
+   * Name or path of the output files. If not provided, the input file will be overwritten.
    *
-   * Default output is same as input.
+   * @default input 
    */
   output?: string;
 
   /**
    * Ignore patterns if input is a glob pattern
    *
-   * By default `node_modules`, `dist` and `.*` files are ignored.
+   * @default ["node_modules", "dist", "/.*"]
    */
   ignore?: string[];
 
diff --git a/src/generator.ts b/src/generator.ts
index 8505991..0bce9d7 100644
--- a/src/generator.ts
+++ b/src/generator.ts
@@ -10,9 +10,23 @@ export interface GenerateContext {
   transform: (contents: string) => Promise<TransformResult>;
 }
 
+/**
+ * The result of generating a component.
+ */
 export interface GenerateResult {
+  /**
+   * The generated component
+   */
   contents: string;
+
+  /**
+   * A list of issues that occurred during generation.
+   */
   issues?: string[];
+
+  /**
+   * Whether to unwrap the component.
+   */
   unwrap?: boolean;
 }
 
diff --git a/src/transform.ts b/src/transform.ts
index 4b469e5..759c926 100644
--- a/src/transform.ts
+++ b/src/transform.ts
@@ -5,13 +5,50 @@ import { Block, containsAutomd, findBlocks, parseRawArgs } from "./_parse";
 import { Config, ResolvedConfig, resolveConfig } from "./config";
 
 export interface TransformResult {
+  /**
+   * Wether if the document has been modified at all.
+   */
   hasChanged: boolean;
+
+  /**
+   * Whether if there were any problems found in the document.
+   */
   hasIssues: boolean;
+
+  /**
+   * The text of the document after it was transformed.
+   */
   contents: string;
-  updates: { block: Block; result: GenerateResult }[];
+
+  /**
+   * A list of specific parts that have been transformed in the document.
+   */
+  updates: {
+    /**
+    * The specific part of the document that has been transformed.
+    */
+    block: Block;
+
+    /**
+     * What the transform has done to this part of the document.
+     */
+    result: GenerateResult
+  }[];
+
+  /**
+   * How long the editing process took, measured in milliseconds.
+   */
   time: number;
 }
 
+/**
+ * Edits a markdown document based on certain rules and configurations.
+ * 
+ * @param contents - The text of the markdown document you want to edit.
+ * @param _config - Optional. The settings that affect how the document will be edited. See {@link Config}.
+ * @param url - Optional. The URL associated with the document, if any.
+ * @returns - The result of the transformation, including any changes made and how long it took. See {@link TransformResult}.
+ */
 export async function transform(
   contents: string,
   _config?: Config,