docs: add library API docstrings

Author: legopitstop

libraries/mc-common/src/constants.ts

@@ -1,11 +1,23 @@
 import { Vector3, RGB, RGBA } from "@minecraft/server";
 
+/**
+ * Type definition for a property value.
+ */
 export type PropertyValue = string | number | boolean | Vector3 | undefined;
 
+/**
+ * Shared max effect value.
+ */
 export const MAX_EFFECT = 20000000;
 
+/**
+ * Shared center entity value.
+ */
 export const CENTER_ENTITY = { x: 0.5, y: 0, z: 0.5 };
 
+/**
+ * Type definition for a color.
+ */
 export type Color = RGBA | RGB;
 
 /**
@@ -45,6 +57,9 @@ export namespace Colors {
   export const Clear: RGBA = { ...Colors.Black, alpha: 0 };
 }
 
+/**
+ * Shared replaceable blocks value.
+ */
 export const REPLACEABLE_BLOCKS = [
   "vine",
   "fern",
@@ -61,6 +76,9 @@ export const REPLACEABLE_BLOCKS = [
   "snow_layer",
 ];
 
+/**
+ * Shared candles value.
+ */
 export const CANDLES = [
   "candle",
   "white_candle",
@@ -81,6 +99,9 @@ export const CANDLES = [
   "pink_candle",
 ];
 
+/**
+ * Shared colors value.
+ */
 export const COLORS = [
   "white",
   "light_gray",
@@ -100,6 +121,9 @@ export const COLORS = [
   "pink",
 ];
 
+/**
+ * Shared wood types value.
+ */
 export const WOOD_TYPES = [
   "oak",
   "spruce",
@@ -115,6 +139,9 @@ export const WOOD_TYPES = [
   "warped",
 ];
 
+/**
+ * Allowed values for a chat color.
+ */
 export enum ChatColor {
   Aqua = `§b`,
   Black = `§0`,
@@ -146,11 +173,17 @@ export enum ChatColor {
   Yellow = `§e`,
 }
 
+/**
+ * Allowed values for an environment.
+ */
 export enum Environment {
   Development = "development",
   Production = "production",
 }
 
+/**
+ * Allowed values for an oxidization.
+ */
 export enum Oxidization {
   Normal = 0,
   Exposed = 1,

libraries/mc-common/src/data/data_storage.ts

@@ -4,11 +4,17 @@ import { DataUtils, DynamicObject } from "./utils";
 import { PropertyValue } from "../constants";
 import { DataStorageEvents, DeleteDataEvent, ReadDataEvent, WriteDataEvent } from "./event";
 
+/**
+ * Options for configuring the data storage.
+ */
 export interface DataStorageOptions {
   object?: DynamicObject;
   gzip?: boolean;
 }
 
+/**
+ * Provides data storage behavior.
+ */
 export class DataStorage {
   static instances = new Map<string, DataStorage>();
 
@@ -235,6 +241,9 @@ export class DataStorage {
   onWrite?(): void {}
 }
 
+/**
+ * Interface describing a versioned data.
+ */
 export interface VersionedDataSchema {
   minFormat: number;
   maxFormat: number;
@@ -243,6 +252,9 @@ export interface VersionedDataSchema {
 
 // TODO: Cache gzipped data storage.
 
+/**
+ * Provides versioned data storage behavior.
+ */
 export class VersionedDataStorage extends DataStorage {
   readonly formatVersion: number;
   schemas = new Map<string, VersionedDataSchema>();
@@ -288,12 +300,18 @@ export class VersionedDataStorage extends DataStorage {
   }
 }
 
+/**
+ * Provides local storage behavior.
+ */
 export class LocalStorage extends DataStorage {
   constructor() {
     super("mcutils:local_storage");
   }
 }
 
+/**
+ * Provides session storage behavior.
+ */
 export class SessionStorage extends DataStorage {
   constructor() {
     super("mcutils:session_storage");
@@ -304,7 +322,13 @@ export class SessionStorage extends DataStorage {
   }
 }
 
+/**
+ * Shared local storage value.
+ */
 export const localStorage = new LocalStorage();
+/**
+ * Shared session storage value.
+ */
 export const sessionStorage = new SessionStorage();
 
 // Events

libraries/mc-common/src/data/decode.ts

@@ -1,5 +1,8 @@
 import { ungzip, Data } from "pako";
 
+/**
+ * Utility helpers for decode.
+ */
 export class DecodeUtils {
   /**
    * Decodes a Base64-encoded string into raw bytes.

libraries/mc-common/src/data/dynamic_storage.ts

@@ -1,6 +1,9 @@
 import { Vector3 } from "@minecraft/server";
 import { DataStorageOptions, VersionedDataStorage } from "./data_storage";
 
+/**
+ * Provides dynamic storage behavior.
+ */
 export class DynamicStorage {
   readonly store: VersionedDataStorage;
 

libraries/mc-common/src/data/encode.ts

@@ -1,5 +1,8 @@
 import { gzip as pakoGZip, Uint8ArrayReturnType } from "pako";
 
+/**
+ * Utility helpers for encode.
+ */
 export class EncodeUtils {
   /**
    * Compresses the provided string to gzip format.

libraries/mc-common/src/data/event.ts

@@ -1,6 +1,9 @@
 import { DataStorage } from "../data";
 import { EventSignal } from "../event";
 
+/**
+ * Event payload for data callbacks.
+ */
 export abstract class DataEvent {
   constructor(store: DataStorage, propertyName?: string) {
     this.store = store;
@@ -11,18 +14,39 @@ export abstract class DataEvent {
   readonly propertyName: string | undefined;
 }
 
+/**
+ * Event payload for read data callbacks.
+ */
 export class ReadDataEvent extends DataEvent {}
 
+/**
+ * Event payload for write data callbacks.
+ */
 export class WriteDataEvent extends DataEvent {}
 
+/**
+ * Event payload for delete data callbacks.
+ */
 export class DeleteDataEvent extends DataEvent {}
 
+/**
+ * Event signal for subscribing to read data events.
+ */
 export class ReadDataEventSignal extends EventSignal<ReadDataEvent> {}
 
+/**
+ * Event signal for subscribing to write data events.
+ */
 export class WriteDataEventSignal extends EventSignal<WriteDataEvent> {}
 
+/**
+ * Event signal for subscribing to delete data events.
+ */
 export class DeleteDataEventSignal extends EventSignal<DeleteDataEvent> {}
 
+/**
+ * Provides data storage events behavior.
+ */
 export class DataStorageEvents {
   private constructor() {}
 

libraries/mc-common/src/data/utils.ts

@@ -27,6 +27,9 @@ import { ConditionUtils } from "../validation";
  */
 export type DynamicObject = World | Entity | ItemStack | ContainerSlot;
 
+/**
+ * Utility helpers for data.
+ */
 export abstract class DataUtils {
   /**
    * Creates a deep copy of JSON data.

libraries/mc-common/src/error.ts

@@ -4,6 +4,9 @@
 
 import { LocationInUnloadedChunkError, LocationOutOfWorldBoundariesError } from "@minecraft/server";
 
+/**
+ * Utility helpers for error.
+ */
 export class ErrorUtils {
   /**
    * Wraps the callback in a try-catch statement, making the error silent.
@@ -61,11 +64,17 @@ export class ErrorUtils {
   }
 }
 
+/**
+ * Interface describing a validation issue.
+ */
 export interface ValidationIssue {
   path: string;
   message: string;
 }
 
+/**
+ * Provides validation error behavior.
+ */
 export class ValidationError extends Error {
   public readonly issues: ValidationIssue[];
 

libraries/mc-common/src/event/utils.ts

@@ -1,8 +1,14 @@
+/**
+ * Interface describing an event listener.
+ */
 export interface EventListener<T, O> {
   callback: (event: T) => void;
   options?: O;
 }
 
+/**
+ * Event signal for subscribing to event signal events.
+ */
 export abstract class EventSignal<T, O = undefined> {
   listeners: EventListener<T, O>[] = [];
 

libraries/mc-common/src/identifier.ts

@@ -11,6 +11,9 @@ import {
   ItemType,
 } from "@minecraft/server";
 
+/**
+ * Type definition for an id.
+ */
 export type Id =
   | string
   | String
@@ -26,6 +29,9 @@ export type Id =
   | EffectType
   | EnchantmentType;
 
+/**
+ * Provides identifier behavior.
+ */
 export class Identifier {
   namespace: string;
   path: string;