docs(archive): mark public APIs as unstable/experimental (#5639)

* BREAKING(archive): remove `TarEntry.#header` * docs(archive): mark public APIs as unstable/experimental
denoland · Aug 6, 2024 · 889a63d · 889a63d
1 parent 0672557
commit 889a63d
Show file tree

Hide file tree

Showing 4 changed files with 84 additions and 8 deletions.
diff --git a/archive/_common.ts b/archive/_common.ts
@@ -3,7 +3,14 @@
 import { PartialReadError } from "@std/io/buf-reader";
 import type { Reader } from "@std/io/types";
 
-/** Base interface for {@linkcode TarMeta} */
+/**
+ * Base interface for {@linkcode TarMeta}.
+ *
+ * > [!WARNING]
+ * > **UNSTABLE**: New API, yet to be vetted.
+ *
+ * @experimental
+ */
 export interface TarInfo {
   /**
    * The underlying raw `st_mode` bits that contain the standard Unix
@@ -37,7 +44,14 @@ export interface TarInfo {
   type?: string;
 }
 
-/** Base interface for {@linkcode TarMetaWithLinkName}. */
+/**
+ * Base interface for {@linkcode TarMetaWithLinkName}.
+ *
+ * > [!WARNING]
+ * > **UNSTABLE**: New API, yet to be vetted.
+ *
+ * @experimental
+ */
 export interface TarMeta extends TarInfo {
   /**
    * The name of the file, with directory names (if any) preceding the file

diff --git a/archive/mod.ts b/archive/mod.ts
@@ -62,6 +62,11 @@
  * writer.close();
  * ```
  *
+ * > [!WARNING]
+ * > **UNSTABLE**: New API, yet to be vetted.
+ *
+ * @experimental
+ *
  * @module
  */
 export * from "./tar.ts";

diff --git a/archive/tar.ts b/archive/tar.ts
@@ -41,7 +41,14 @@ import { HEADER_LENGTH } from "./_common.ts";
 
 export type { TarInfo, TarMeta };
 
-/** Options for {@linkcode Tar.append}. */
+/**
+ * Options for {@linkcode Tar.append}.
+ *
+ * > [!WARNING]
+ * > **UNSTABLE**: New API, yet to be vetted.
+ *
+ * @experimental
+ */
 export interface TarOptions extends TarInfo {
   /**
    * Filepath of the file to append to the archive
@@ -115,7 +122,14 @@ function formatHeader(data: TarData): Uint8Array {
   return buffer;
 }
 
-/** Base interface for {@linkcode TarDataWithSource}. */
+/**
+ * Base interface for {@linkcode TarDataWithSource}.
+ *
+ * > [!WARNING]
+ * > **UNSTABLE**: New API, yet to be vetted.
+ *
+ * @experimental
+ */
 export interface TarData {
   /** Name of the file, excluding directory names (if any). */
   fileName?: string;
@@ -162,7 +176,14 @@ export interface TarData {
   group?: string;
 }
 
-/** Tar data interface for {@linkcode Tar.data}. */
+/**
+ * Tar data interface for {@linkcode Tar.data}.
+ *
+ * > [!WARNING]
+ * > **UNSTABLE**: New API, yet to be vetted.
+ *
+ * @experimental
+ */
 export interface TarDataWithSource extends TarData {
   /**
    * Path of the file to read.
@@ -228,6 +249,11 @@ export interface TarDataWithSource extends TarData {
  * await copy(tar.getReader(), writer);
  * writer.close();
  * ```
+ *
+ * > [!WARNING]
+ * > **UNSTABLE**: New API, yet to be vetted.
+ *
+ * @experimental
  */
 export class Tar {
   /** Tar data. */

diff --git a/archive/untar.ts b/archive/untar.ts
@@ -43,13 +43,25 @@ import type { Reader } from "@std/io/types";
 /**
  * Extend TarMeta with the `linkName` property so that readers can access
  * symbolic link values without polluting the world of archive writers.
+ *
+ * > [!WARNING]
+ * > **UNSTABLE**: New API, yet to be vetted.
+ *
+ * @experimental
  */
 export interface TarMetaWithLinkName extends TarMeta {
   /** File name of the symbolic link. */
   linkName?: string;
 }
 
-/** Tar header with raw, unprocessed bytes as values. */
+/**
+ * Tar header with raw, unprocessed bytes as values.
+ *
+ * > [!WARNING]
+ * > **UNSTABLE**: New API, yet to be vetted.
+ *
+ * @experimental
+ */
 export type TarHeader = {
   [key in UstarFields]: Uint8Array;
 };
@@ -85,10 +97,24 @@ function parseHeader(buffer: Uint8Array): TarHeader {
   return data;
 }
 
-/** Tar entry */
+/**
+ * Tar entry
+ *
+ * > [!WARNING]
+ * > **UNSTABLE**: New API, yet to be vetted.
+ *
+ * @experimental
+ */
 export interface TarEntry extends TarMetaWithLinkName {}
 
-/** Contains tar header metadata and a reader to the entry's body. */
+/**
+ * Contains tar header metadata and a reader to the entry's body.
+ *
+ * > [!WARNING]
+ * > **UNSTABLE**: New API, yet to be vetted.
+ *
+ * @experimental
+ */
 export class TarEntry implements Reader {
   #reader: Reader | (Reader & Deno.Seeker);
   #size: number;
@@ -218,6 +244,11 @@ export class TarEntry implements Reader {
  *   await copy(entry, file);
  * }
  * ```
+ *
+ * > [!WARNING]
+ * > **UNSTABLE**: New API, yet to be vetted.
+ *
+ * @experimental
  */
 export class Untar {
   /** Internal reader. */