Add jsdoc comments for public API

Changes

14 changed files (+149/-4)

• content_parser/json_canvas.ts
  • @@ -38,6 +38,11 @@ "json_canvas",
    JSONCanvas<T> >; + /** + * Content parser for JSONCanvas documents. + * + * This parser uses Obsidian Markdown parser internally. + */ export class JSONCanvasParser implements ContentParser<JSONCanvasDocument<Mdast.Nodes>> { async parse(
• content_parser/obsidian_markdown.ts
  • @@ -94,6 +94,9 @@ */
    frontmatter?: boolean; } + /** + * @internal + */ export async function parseMarkdown( markdown: string | Uint8Array, { getAssetToken, getDocumentToken }: Pick<
  • @@ -237,6 +240,9 @@ },
    }; } + /** + * Content parser for Obsidian Flavored Markdown documents. + */ export class ObsidianMarkdownParser implements ContentParser<ObsidianMarkdownDocument> { #frontmatter: boolean;
• content_parser/oneof.ts
  • @@ -4,6 +4,13 @@ // SPDX-License-Identifier: Apache-2.0
    import type { ContentParser } from "./interface.ts"; + /** + * Combine multiple content parsers into one. + * + * It tries to parse the contents using given parsers and returns the first + * successful result. If all of parsers failed, this parser throws the last + * thrown error. + */ export function oneof(...parsers: readonly ContentParser[]): ContentParser { return { async parse(...args) {
• docs/build.ts
  • @@ -2,6 +2,14 @@ // SPDX-FileCopyrightText: 2024 Shota FUJI <pockawoooh@gmail.com>
    // // SPDX-License-Identifier: Apache-2.0 + /** + * @internal + * + * Build script for Macana's document website. + * + * @module + */ + import * as log from "../deps/deno.land/std/log/mod.ts"; import * as cli from "../deps/deno.land/std/cli/mod.ts"; import * as colors from "../deps/deno.land/std/fmt/colors.ts";
• filesystem_reader/deno_fs.ts
  • @@ -13,6 +13,11 @@ FileReader,
    RootDirectoryReader, } from "../types.ts"; + /** + * FileSystem Reader for native file system, using Deno runtime API. + * + * This writer requires "read" permission for the `rootDirectory`. + */ export class DenoFsReader implements FileSystemReader { #root: string;
• filesystem_reader/memory_fs.ts
  • @@ -30,7 +30,7 @@
    /** * In-memory readonly filesystem. * - * This was created for testing purpose. + * This is for testing. */ export class MemoryFsReader implements FileSystemReader { #tree: InternalTree;
• filesystem_writer/deno_fs.ts
  • @@ -8,6 +8,11 @@ import { logger } from "../logger.ts";
    import type { FileSystemWriter } from "./interface.ts"; + /** + * FileSystem Writer for native file system, using Deno runtime API. + * + * This writer requires "write" permission for the `rootDirectory`. + */ export class DenoFsWriter implements FileSystemWriter { #root: string; #wroteHash: Map<string, Uint8Array> = new Map();
• filesystem_writer/memory_fs.ts
  • @@ -6,6 +6,13 @@ import type { FileSystemWriter } from "./interface.ts";
    const SEP = "/"; + /** + * Write contents to in-memory `Map` object. + * + * This is for testing: this class does not implement iterator + * or a listing method. If you need in-memory abstraction or such, + * write your own. + */ export class MemoryFsWriter implements FileSystemWriter { #files: Map<string, Uint8Array> = new Map();
• filesystem_writer/no_overwrite.ts
  • @@ -9,9 +9,45 @@
    const SEP = "/"; /** - * Wraps the given FileSystem Writer and returns a new FileSystem Writer - * that prevents writes to the same location with different content. - * It also suppress redundant writes if the content hash is same. + * Skip duplicated file writes. + * + * This function wraps FileSystem Writer and returns a new FileSystem Writer + * that skips duplicated file write operations. + * + * For example, bare FileSystem Writers perform two writes below: + * + * ```ts + * const content = new TextEncoder().encode("Hello, World"); + * + * const fsw = new DenoFsWriter(".dist"); + * + * await fsw.write(["foo.txt"], content); // OS file write to .dist/foo.txt + * await fsw.write(["foo.txt"], content); // OS file write to .dist/foo.txt + * ``` + * + * With this function, you can eliminate the second redundant call. + * + * ```ts + * const content = new TextEncoder().encode("Hello, World"); + * + * const fsw = noOverwrite(new DenoFsWriter(".dist")); + * + * await fsw.write(["foo.txt"], content); // OS file write to .dist/foo.txt + * await fsw.write(["foo.txt"], content); // Function returns without actual file I/O + * ``` + * + * If the hash of content to write differs from the previous actual write, + * this function throws an error. + * + * ```ts + * const fsw = noOverwrite(new DenoFsWriter(".dist")); + * + * await fsw.write(["foo.txt"], new TextEncoder().encode("Hello, World")); // OS file write to .dist/foo.txt + * await fsw.write(["foo.txt"], new TextEncoder().encode("Bye, World")); // Throws an error + * ``` + * + * @param childWriter - FileSystem Writer that performs actual write operation. + * @returns Wrapped FileSystem Writer. */ export function noOverwrite(childWriter: FileSystemWriter): FileSystemWriter { const hashes = new Map<string, string>();
• filesystem_writer/validate_tree.ts
  • @@ -24,6 +24,9 @@ /**
    * Wraps the given FileSystem Writer and returns a new FileSystem Writer * that checks tree structure so there won't be a directory and a file * having same name. + * + * If you're writing to native file system, you won't need this function + * as the native file system validates using its own constraints. */ export function validateTree(childWriter: FileSystemWriter): FileSystemWriter { const nodes = new Map<string, NodeType>();
• logger.ts
  • @@ -4,6 +4,17 @@ // SPDX-License-Identifier: Apache-2.0
    import { getLogger } from "./deps/deno.land/std/log/mod.ts"; + /** + * @internal + * + * Logging interface for Macana internals. + * + * @module + */ + + /** + * @internal + */ export function logger() { return getLogger("macana"); }
• page_builder/default_theme/mod.ts
  • @@ -2,6 +2,16 @@ // SPDX-FileCopyrightText: 2024 Shota FUJI <pockawoooh@gmail.com>
    // // SPDX-License-Identifier: Apache-2.0 + /** + * Macana's default page builder. + * + * Files in this directory other than `mod.ts` are for internal use. + * You should not use those: changes to those files are outside scope of + * semantic versioning. + * + * @module + */ + import type * as Hast from "../../deps/esm.sh/hast/types.ts"; import type * as Mdast from "../../deps/esm.sh/mdast/types.ts"; import { headingRange } from "../../deps/esm.sh/mdast-util-heading-range/mod.ts";
  • @@ -130,6 +140,13 @@ */
    siteLogo?: readonly string[]; } + /** + * Macana's default page builder. + * + * This takes a document tree generated by Tree Builder then writes converted + * HTML using FileSystem Writer. It would also read non-document files using + * FileSystem Reader. + */ export class DefaultThemeBuilder implements PageBuilder { #copyright: string; #faviconSvg?: readonly string[];
• tree_builder/default_tree_builder.ts
  • @@ -69,10 +69,30 @@ return { skip: true };
    }; } + /** + * Do not include files and directories whose name starts with dot (`.`). + */ export const ignoreDotfiles: IgnoreFunction = (node) => { return node.name.startsWith("."); }; + /** + * Treat specific named directories as language directory. + * Contents inside the language directory inherits its document language + * from the language directory, if the document does not have its own language + * set. + * + * @param langs - Map of directory name and display name. + * @param topLevelOnly - Whether this function skip non-toplevel directories. + * + * @example + * langDir({ + * // Directories named "en" is set to "lang=en" and displayed as "English" + * "en": "English", + * // Directories named "kr" is set to "lang=kr" and displayed as "Korean" + * "kr": "Korean", + * }) + */ export function langDir( langs: Record<string, string>, topLevelOnly: boolean = false,
  • @@ -408,6 +428,12 @@ */
    resolveShortestPathWhenPossible?: boolean; } + /** + * Macana's default tree builder. + * + * This tree builder prioritizes effortlessly building a tree from + * vanilla Obsidian Vault. + */ export class DefaultTreeBuilder implements TreeBuilder { #defaultLanguage: string; #strategies: readonly TreeBuildStrategy[];
• types.ts
  • @@ -7,6 +7,9 @@ contentUpdatedAt?: Date;
    createdAt?: Date; } + /** + * Virtual readonly file system's file. + */ export interface FileReader { readonly type: "file"; readonly name: string;
  • @@ -18,6 +21,9 @@
    stat(): FileSystemStats | Promise<FileSystemStats>; } + /** + * Virtual readonly file system's directory. + */ export interface DirectoryReader { readonly type: "directory"; readonly name: string;
  • @@ -33,6 +39,9 @@ export type DocumentToken = `mxt_${string}`;
    export type AssetToken = `mxa_${string}`; + /** + * Virtual readonly file system's root directory. + */ export interface RootDirectoryReader { readonly type: "root";