From 2cbaab58814633f2e41472c8cfd7d9ee1c468e08 Mon Sep 17 00:00:00 2001 From: uki00a Date: Wed, 1 Jan 2025 15:28:29 +0900 Subject: [PATCH] test(log): re-enable doc tests for `FileHandler` --- .gitignore | 2 + _tmp/.keep | 0 _tools/check_docs.ts | 11 +++- _tools/check_licence.ts | 1 + log/file_handler.ts | 123 ++++++++++++---------------------------- 5 files changed, 47 insertions(+), 90 deletions(-) create mode 100644 _tmp/.keep diff --git a/.gitignore b/.gitignore index 02be11f2662b..4eea860951e5 100644 --- a/.gitignore +++ b/.gitignore @@ -19,3 +19,5 @@ codecov.SHA256SUM.sig .DS_Store .idea .vim +_tmp/ +!_tmp/.keep diff --git a/_tmp/.keep b/_tmp/.keep new file mode 100644 index 000000000000..e69de29bb2d1 diff --git a/_tools/check_docs.ts b/_tools/check_docs.ts index 895c7e81ab58..f01eeb61579e 100644 --- a/_tools/check_docs.ts +++ b/_tools/check_docs.ts @@ -273,16 +273,21 @@ function assertSnippetsWork( function assertHasExampleTag( document: { jsDoc: JsDoc; location: Location }, ) { - const tags = document.jsDoc.tags?.filter((tag) => + const exampleTags = document.jsDoc.tags?.filter((tag) => tag.kind === "example" ) as JsDocTagDocRequired[]; - if (tags === undefined || tags.length === 0) { + const hasNoExampleTags = exampleTags === undefined || + exampleTags.length === 0; + if ( + hasNoExampleTags && + !document.jsDoc.tags?.some((tag) => tag.kind === "private") + ) { diagnostics.push( new DocumentError("Symbol must have an @example tag", document), ); return; } - for (const tag of tags) { + for (const tag of exampleTags) { assert( tag.doc !== undefined, "@example tag must have a title and TypeScript code snippet", diff --git a/_tools/check_licence.ts b/_tools/check_licence.ts index 41b8237400ac..2e9ea8ab2a5f 100644 --- a/_tools/check_licence.ts +++ b/_tools/check_licence.ts @@ -13,6 +13,7 @@ const EXCLUDED_DIRS = [ "**/crypto/_wasm/lib", "**/.git", "**/docs/**", + "**/_tmp", ]; const ROOT = new URL("../", import.meta.url); diff --git a/log/file_handler.ts b/log/file_handler.ts index c08e16b087ea..473faef1ac9c 100644 --- a/log/file_handler.ts +++ b/log/file_handler.ts @@ -52,10 +52,10 @@ export interface FileHandlerOptions extends BaseHandlerOptions { * This handler requires `--allow-write` permission on the log file. * * @example Usage - * ```ts no-assert ignore + * ```ts no-assert * import { FileHandler } from "@std/log/file-handler"; * - * const handler = new FileHandler("INFO", { filename: "./logs.txt" }); + * const handler = new FileHandler("INFO", { filename: "./_tmp/logs.txt" }); * handler.setup(); * handler.log('Hello, world!'); // Buffers the message, or writes it to the file depending on buffer state * handler.flush(); // Manually flushes the buffer @@ -64,95 +64,44 @@ export interface FileHandlerOptions extends BaseHandlerOptions { */ export class FileHandler extends BaseHandler { /** Opened file to append logs to. - * @example Usage - * ```ts no-assert ignore - * import { FileHandler } from "@std/log/file-handler"; * - * const handler = new FileHandler("INFO", { filename: "./logs.txt" }); - * handler.setup(); - * handler.log('Hello, world!'); // Buffers the message, or writes it to the file depending on buffer state - * handler.flush(); // Manually flushes the buffer - * handler.destroy(); // Closes the file and removes listeners - * ``` - * **/ + * @private + */ [fileSymbol]: Deno.FsFile | undefined; /** Buffer used to write to file. - * @example Usage - * ```ts no-assert ignore - * import { FileHandler } from "@std/log/file-handler"; * - * const handler = new FileHandler("INFO", { filename: "./logs.txt" }); - * handler.setup(); - * handler.log('Hello, world!'); // Buffers the message, or writes it to the file depending on buffer state - * handler.flush(); // Manually flushes the buffer - * handler.destroy(); // Closes the file and removes listeners - * ``` - * **/ + * @private + */ [bufSymbol]: Uint8Array; - /** Current position for pointer. - * @example Usage - * ```ts no-assert ignore - * import { FileHandler } from "@std/log/file-handler"; + /** + * Current position for pointer. * - * const handler = new FileHandler("INFO", { filename: "./logs.txt" }); - * handler.setup(); - * handler.log('Hello, world!'); // Buffers the message, or writes it to the file depending on buffer state - * handler.flush(); // Manually flushes the buffer - * handler.destroy(); // Closes the file and removes listeners - * ``` - * **/ + * @private + */ [pointerSymbol] = 0; - /** Filename associated with the file being logged. - * @example Usage - * ```ts no-assert ignore - * import { FileHandler } from "@std/log/file-handler"; + /** + * Filename associated with the file being logged. * - * const handler = new FileHandler("INFO", { filename: "./logs.txt" }); - * handler.setup(); - * handler.log('Hello, world!'); // Buffers the message, or writes it to the file depending on buffer state - * handler.flush(); // Manually flushes the buffer - * handler.destroy(); // Closes the file and removes listeners - * ``` - * **/ + * @private + */ [filenameSymbol]: string; - /** Current log mode. - * @example Usage - * ```ts no-assert ignore - * import { FileHandler } from "@std/log/file-handler"; + /** + * Current log mode. * - * const handler = new FileHandler("INFO", { filename: "./logs.txt" }); - * handler.setup(); - * handler.log('Hello, world!'); // Buffers the message, or writes it to the file depending on buffer state - * handler.flush(); // Manually flushes the buffer - * handler.destroy(); // Closes the file and removes listeners - * ``` - * **/ + * @private + */ [modeSymbol]: LogMode; - /** File open options. - * @example Usage - * ```ts no-assert ignore - * import { FileHandler } from "@std/log/file-handler"; + /** + * File open options. * - * const handler = new FileHandler("INFO", { filename: "./logs.txt" }); - * handler.setup(); - * handler.log('Hello, world!'); // Buffers the message, or writes it to the file depending on buffer state - * handler.flush(); // Manually flushes the buffer - * handler.destroy(); // Closes the file and removes listeners - * ``` - * **/ + * @private + */ [openOptionsSymbol]: Deno.OpenOptions; - /** Text encoder. - * @example Usage - * ```ts no-assert ignore - * import { FileHandler } from "@std/log/file-handler"; + /** + * Text encoder. * - * const handler = new FileHandler("INFO", { filename: "./logs.txt" }); - * handler.setup(); - * handler.log('Hello, world!'); // Buffers the message, or writes it to the file depending on buffer state - * handler.flush(); // Manually flushes the buffer - * handler.destroy(); // Closes the file and removes listeners - * ``` - * **/ + * @private + */ [encoderSymbol]: TextEncoder = new TextEncoder(); #unloadCallback = (() => { this.destroy(); @@ -183,10 +132,10 @@ export class FileHandler extends BaseHandler { * Sets up the file handler by opening the specified file and initializing resources. * * @example Usage - * ```ts no-assert ignore + * ```ts no-assert * import { FileHandler } from "@std/log/file-handler"; * - * const handler = new FileHandler("INFO", { filename: "./logs.txt" }); + * const handler = new FileHandler("INFO", { filename: "./_tmp/logs.txt" }); * handler.setup(); // Opens the file and prepares the handler for logging. * handler.destroy(); * ``` @@ -207,13 +156,13 @@ export class FileHandler extends BaseHandler { * @param logRecord Log record to handle. * * @example Usage - * ```ts ignore + * ```ts * import { FileHandler } from "@std/log/file-handler"; * import { assertInstanceOf } from "@std/assert/instance-of"; * import { LogLevels } from "./levels.ts"; * import { LogRecord } from "./logger.ts"; * - * const handler = new FileHandler("INFO", { filename: "./logs.txt" }); + * const handler = new FileHandler("INFO", { filename: "./_tmp/logs.txt" }); * handler.setup(); * * // Flushes the buffer immediately and logs "CRITICAL This log is very critical indeed." into the file. @@ -245,11 +194,11 @@ export class FileHandler extends BaseHandler { * @param msg The message to log. * * @example Usage - * ```ts ignore + * ```ts * import { FileHandler } from "@std/log/file-handler"; * import { assertInstanceOf } from "@std/assert/instance-of"; * - * const handler = new FileHandler("INFO", { filename: "./logs.txt" }); + * const handler = new FileHandler("INFO", { filename: "./_tmp/logs.txt" }); * handler.setup(); * handler.log('Hello, world!'); * handler.flush(); @@ -275,11 +224,11 @@ export class FileHandler extends BaseHandler { * Immediately writes the contents of the buffer to the previously opened file. * * @example Usage - * ```ts ignore + * ```ts * import { FileHandler } from "@std/log/file-handler"; * import { assertInstanceOf } from "@std/assert/instance-of"; * - * const handler = new FileHandler("INFO", { filename: "./logs.txt" }); + * const handler = new FileHandler("INFO", { filename: "./_tmp/logs.txt" }); * handler.setup(); * handler.log('Hello, world!'); * handler.flush(); // Writes buffered log messages to the file immediately. @@ -308,11 +257,11 @@ export class FileHandler extends BaseHandler { * Destroys the handler, performing any cleanup that is required and closes the file handler. * * @example Usage - * ```ts ignore + * ```ts * import { FileHandler } from "@std/log/file-handler"; * import { assertInstanceOf } from "@std/assert/instance-of"; * - * const handler = new FileHandler("INFO", { filename: "./logs.txt" }); + * const handler = new FileHandler("INFO", { filename: "./_tmp/logs.txt" }); * handler.setup(); * handler.destroy(); *