docs: improve module JSDoc for archive, async, bytes (#2162)

archive/tar.ts

@@ -27,6 +27,69 @@
  * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
  * THE SOFTWARE.
  */
+
+/**
+ * Provides a `Tar` and `Untar` classes for compressing and decompressing
+ * arbitrary data.
+ *
+ * ## Examples
+ *
+ * ### Tar
+ *
+ * ```ts
+ * import { Tar } from "https://deno.land/std@$STD_VERSION/archive/tar.ts";
+ * import { Buffer } from "https://deno.land/std@$STD_VERSION/io/buffer.ts";
+ * import { copy } from "https://deno.land/std@$STD_VERSION/streams/conversion.ts";
+ *
+ * const tar = new Tar();
+ * const content = new TextEncoder().encode("Deno.land");
+ * await tar.append("deno.txt", {
+ *   reader: new Buffer(content),
+ *   contentSize: content.byteLength,
+ * });
+ *
+ * // Or specifying a filePath.
+ * await tar.append("land.txt", {
+ *   filePath: "./land.txt",
+ * });
+ *
+ * // use tar.getReader() to read the contents.
+ *
+ * const writer = await Deno.open("./out.tar", { write: true, create: true });
+ * await copy(tar.getReader(), writer);
+ * writer.close();
+ * ```
+ *
+ * ### Untar
+ *
+ * ```ts
+ * import { Untar } from "https://deno.land/std@$STD_VERSION/archive/tar.ts";
+ * import { ensureFile } from "https://deno.land/std@$STD_VERSION/fs/ensure_file.ts";
+ * import { ensureDir } from "https://deno.land/std@$STD_VERSION/fs/ensure_dir.ts";
+ * import { copy } from "https://deno.land/std@$STD_VERSION/streams/conversion.ts";
+ *
+ * const reader = await Deno.open("./out.tar", { read: true });
+ * const untar = new Untar(reader);
+ *
+ * for await (const entry of untar) {
+ *   console.log(entry); // metadata
+ *
+ *   if (entry.type === "directory") {
+ *     await ensureDir(entry.fileName);
+ *     continue;
+ *   }
+ *
+ *   await ensureFile(entry.fileName);
+ *   const file = await Deno.open(entry.fileName, { write: true });
+ *   // <entry> is a reader.
+ *   await copy(entry, file);
+ * }
+ * reader.close();
+ * ```
+ *
+ * @module
+ */
+
 import { MultiReader } from "../io/readers.ts";
 import { Buffer, PartialReadError } from "../io/buffer.ts";
 import { assert } from "../_util/assert.ts";

async/mod.ts

@@ -1,4 +1,11 @@
 // Copyright 2018-2022 the Deno authors. All rights reserved. MIT license.
+
+/**
+ * A collection of APIs to provide help with asynchronous tasks.
+ *
+ * @module
+ */
+
 export * from "./abortable.ts";
 export * from "./deadline.ts";
 export * from "./debounce.ts";

bytes/mod.ts

@@ -1,6 +1,13 @@
 // Copyright 2018-2022 the Deno authors. All rights reserved. MIT license.
 // This module is browser compatible.
 
+/**
+ * Provides helper functions to manipulate `Uint8Array` byte slices that are not
+ * included on the `Uint8Array` prototype.
+ *
+ * @module
+ */
+
 /** Returns the index of the first occurrence of the needle array in the source
  * array, or -1 if it is not present.
  *