Merge pull request #1 from basic-examples/codex/add-tsdoc-comments-and-readme.md-for-subpackages

Improve docs

Author: mjy9088

packages/parser/README.md

@@ -0,0 +1,3 @@
+# `@ansi-escape-code/parser`
+
+Utilities for parsing strings that contain ANSI escape sequences.

packages/parser/src/index.ts

@@ -1,12 +1,14 @@
 import { AnsiColor, AnsiString } from "@ansi-escape-code/type";
 
+/** Options controlling how ANSI strings are parsed. */
 export interface ParseAnsiStringOptions {
   flags?: number;
   underlineColor?: AnsiColor;
   foregroundColor?: AnsiColor;
   backgroundColor?: AnsiColor;
 }
 
+/** Successful result returned from {@link parseAnsiString}. */
 export interface ParseAnsiStringResultOk {
   success: true;
   ansiString: AnsiString[];
@@ -16,6 +18,7 @@ export interface ParseAnsiStringResultOk {
   remainBackgroundColor: AnsiColor;
 }
 
+/** Error result returned from {@link parseAnsiString}. */
 export interface ParseAnsiStringResultError {
   success: false;
   error: "unclosed-escape-sequence" | ParseAnsiStringFlagsResultError["error"];
@@ -25,6 +28,9 @@ export type ParseAnsiStringResult =
   | ParseAnsiStringResultOk
   | ParseAnsiStringResultError;
 
+/**
+ * Parses a string containing ANSI escape sequences.
+ */
 export function parseAnsiString(
   input: string,
   {
@@ -100,6 +106,7 @@ export function parseAnsiString(
   };
 }
 
+/** Successful result returned from {@link parseAnsiStringFlags}. */
 export interface ParseAnsiStringFlagsResultOk {
   success: true;
   flags: number;
@@ -108,6 +115,7 @@ export interface ParseAnsiStringFlagsResultOk {
   backgroundColor: AnsiColor;
 }
 
+/** Error result returned from {@link parseAnsiStringFlags}. */
 export interface ParseAnsiStringFlagsResultError {
   success: false;
   error: "invalid-flags";
@@ -117,6 +125,9 @@ export type ParseAnsiStringFlagsResult =
   | ParseAnsiStringFlagsResultOk
   | ParseAnsiStringFlagsResultError;
 
+/**
+ * Parses an array of numeric SGR codes.
+ */
 export function parseAnsiStringFlags(
   input: number[],
   {

packages/type/README.md

@@ -0,0 +1,3 @@
+# `@ansi-escape-code/type`
+
+Type definitions used across the ansi-escape-code packages.

packages/type/src/index.ts

@@ -43,6 +43,9 @@ export class AnsiString {
 
   static readonly UNKNOWN_BIT = 16384; // 1 << 14
 
+  /**
+   * Creates a new {@link AnsiString} instance.
+   */
   constructor(
     public readonly content: string,
     public readonly attributeFlags: number,

src/NoopAnsi.ts

@@ -1,9 +1,20 @@
 import { AnsiOptions, AnsiPart, Ansi as DefaultAnsi } from ".";
+/**
+ * Variant of {@link DefaultAnsi} that ignores all styling and simply
+ * concatenates the contained parts.
+ */
 
 export class NoopAnsi extends DefaultAnsi {
+  /**
+   * @param _unusedOptions - Ignored styling options.
+   * @param parts - Content parts to combine.
+   */
   constructor(_unusedOptions: Partial<AnsiOptions>, ...parts: AnsiPart[]) {
     super({}, ...parts);
   }
+  /**
+   * Renders contained parts without escape sequences.
+   */
 
   public toString(_unusedResolvedOuterOptions?: AnsiOptions): string {
     return NoopAnsi.toStringInternal(this.parts);

src/index.ts

@@ -1,7 +1,12 @@
 import type { AnsiColor } from "@ansi-escape-code/type";
 
+/**
+ * Union of parts that can make up an ANSI string. A part can be another
+ * {@link Ansi} instance or any object with a `toString()` method.
+ */
 export type AnsiPart = Ansi | { toString(): string };
 
+/** Options describing how text should be styled. */
 export interface AnsiOptions {
   weight: "normal" | "bold" | "dim";
   italic: boolean;
@@ -15,11 +20,20 @@ export interface AnsiOptions {
   backgroundColor: AnsiColor;
 }
 
+/**
+ * Template tag used to produce nested {@link Ansi} instances.
+ *
+ * @param strings - Raw template string segments.
+ * @param values - Interpolated values to embed.
+ */
 export type AnsiTemplateTag = (
   strings: TemplateStringsArray,
   ...values: readonly AnsiPart[]
 ) => Ansi;
 
+/**
+ * Represents a styled string that can contain nested {@link Ansi} parts.
+ */
 export class Ansi {
   public static readonly defaultOptions: AnsiOptions = {
     weight: "normal",
@@ -36,13 +50,24 @@ export class Ansi {
 
   public readonly parts: AnsiPart[];
 
+  /**
+   * Creates a new instance.
+   *
+   * @param options - Styling options to apply to the contents.
+   * @param parts - Parts that make up the styled output.
+   */
   constructor(
     public readonly options: Partial<AnsiOptions>,
     ...parts: AnsiPart[]
   ) {
     this.parts = parts;
   }
 
+  /**
+   * Renders this instance and all nested parts to a string.
+   *
+   * @param resolvedOuterOptions - Active options of the parent context.
+   */
   public toString(
     resolvedOuterOptions: AnsiOptions = Ansi.defaultOptions
   ): string {
@@ -236,10 +261,20 @@ export class Ansi {
     return [5, 16 + r * 36 + g * 6 + b];
   }
 
+  /**
+   * Creates a 24 bit true color value.
+   *
+   * @param r - Red component (0-255)
+   * @param g - Green component (0-255)
+   * @param b - Blue component (0-255)
+   */
   public static TRUE_COLOR(r: number, g: number, b: number): AnsiColor {
     return [2, r, g, b];
   }
 
+  /**
+   * Returns a template tag preconfigured with the provided options.
+   */
   public static tt(oprions: Partial<AnsiOptions>): AnsiTemplateTag {
     const options = (oprions ?? {}) as Partial<AnsiOptions>;
     return (strings: TemplateStringsArray, ...values: AnsiPart[]) => {
@@ -249,6 +284,9 @@ export class Ansi {
   }
 }
 
+/**
+ * Interleaves template string segments with their interpolated values.
+ */
 function interleave(
   strings: TemplateStringsArray,
   values: readonly AnsiPart[]