Add documentation blocks for all base64 encoders and decoders

Author: jeskew

packages/types/util.ts

@@ -1,7 +1,23 @@
+/**
+ * A function that, given a TypedArray of bytes, can produce a string
+ * representation thereof.
+ *
+ * @example An encoder function that converts bytes to hexadecimal
+ * representation would return `'deadbeef'` when given `new
+ * Uint8Array([0xde, 0xad, 0xbe, 0xef])`.
+ */
 export interface Encoder {
   (input: Uint8Array): string;
 }
 
+/**
+ * A function that, given a string, can derive the bytes represented by that
+ * string.
+ *
+ * @example A decoder function that converts bytes to hexadecimal
+ * representation would return `new Uint8Array([0xde, 0xad, 0xbe, 0xef])` when
+ * given the string `'deadbeef'`.
+ */
 export interface Decoder {
   (input: string): Uint8Array;
 }

packages/util-base64-browser/index.ts

@@ -39,6 +39,13 @@ const bitsPerLetter = 6;
 const bitsPerByte = 8;
 const maxLetterValue = 0b111111;
 
+/**
+ * Converts a base-64 encoded string to a Uint8Array of bytes.
+ *
+ * @param input The base-64 encoded string
+ *
+ * @see https://tools.ietf.org/html/rfc4648#section-4
+ */
 export function fromBase64(input: string): Uint8Array {
   let totalByteLength = (input.length / 4) * 3;
   if (input.substr(-2) === "==") {
@@ -72,6 +79,13 @@ export function fromBase64(input: string): Uint8Array {
   return new Uint8Array(out);
 }
 
+/**
+ * Converts a Uint8Array of binary data to a base-64 encoded string.
+ *
+ * @param input The binary data to encode
+ *
+ * @see https://tools.ietf.org/html/rfc4648#section-4
+ */
 export function toBase64(input: Uint8Array): string {
   let str = "";
   for (let i = 0; i < input.length; i += 3) {

packages/util-base64-node/index.ts

@@ -1,5 +1,11 @@
 import { Buffer } from "buffer";
 
+/**
+ * Converts a base-64 encoded string to a Uint8Array of bytes using Node.JS's
+ * `buffer` module.
+ *
+ * @param input The base-64 encoded string
+ */
 export function fromBase64(input: string): Uint8Array {
   if (typeof input === "number") {
     throw new Error("Cannot base64 decode a number");
@@ -19,6 +25,12 @@ export function fromBase64(input: string): Uint8Array {
   );
 }
 
+/**
+ * Converts a Uint8Array of binary data to a base-64 encoded string using
+ * Node.JS's `buffer` module.
+ *
+ * @param input The binary data to encode
+ */
 export function toBase64(input: Uint8Array): string {
   if (typeof input === "number") {
     throw new Error("Cannot base64 encode a number");

packages/util-base64-universal/index.ts

@@ -8,6 +8,11 @@ import {
   toBase64 as nodeToBase64
 } from "@aws/util-base64-node";
 
+/**
+ * Converts a base-64 encoded string to a Uint8Array of bytes.
+ *
+ * @param input The base-64 encoded string
+ */
 export function fromBase64(input: string): Uint8Array {
   if (isNode()) {
     return nodeFromBase64(input);
@@ -16,6 +21,11 @@ export function fromBase64(input: string): Uint8Array {
   return browserFromBase64(input);
 }
 
+/**
+ * Converts a Uint8Array of binary data to a base-64 encoded string.
+ *
+ * @param input The binary data to encode
+ */
 export function toBase64(input: Uint8Array): string {
   if (isNode()) {
     return nodeToBase64(input);