Added documentation to lib

Author: calebsander

dist/lib/assert.js

@@ -3,6 +3,12 @@ Object.defineProperty(exports, "__esModule", { value: true });
 const util_inspect_1 = require("./util-inspect");
 //A number of useful assertion functions
 //Used in tests and for validations in production
+/**
+ * Throws an error if the given value is not an instance
+ * of any of the provided constructors
+ * @param instance The value in question
+ * @param constructors A constructor or array of constructors to test against
+ */
 function instanceOf(instance, constructors) {
     if (!(constructors instanceof Array))
         constructors = [constructors];
@@ -23,12 +29,25 @@ function instanceOf(instance, constructors) {
                 .join(' or '));
     }
 }
+/**
+ * Throws an error if the given value is not an integer
+ * within the range of integers representable in JavaScript
+ * @param instance The value in question
+ */
 function integer(instance) {
     instanceOf(instance, Number);
     if (!Number.isSafeInteger(instance)) {
         throw new RangeError(util_inspect_1.inspect(instance) + ' is not an integer');
     }
 }
+/**
+ * Throws an error if a numeric value is not between
+ * the given bounds
+ * @param lower The lower bound (inclusive)
+ * @param value The value in question
+ * @param upper The upper bound (exclusive)
+ * @param message An optional message to include in the error message
+ */
 function between(lower, value, upper, message) {
     if (value < lower || value >= upper) {
         const outOfBoundsMessage = util_inspect_1.inspect(value) +
@@ -43,18 +62,38 @@ function between(lower, value, upper, message) {
             throw new RangeError(outOfBoundsMessage);
     }
 }
+/**
+ * Throws an error if the given value is not an integer
+ * and in the range that can be represented in an unsigned byte
+ * @param value The value in question
+ */
 function byteUnsignedInteger(value) {
     integer(value);
     between(0, value, 256);
 }
+/**
+ * Throws an error with the specified message
+ * @param message The message of the thrown error
+ */
 function fail(message) {
     throw new Error(message);
 }
-//Assert that a condition is met if not, throw an error with the specified message
+/**
+ * Throws an error if the provided condition is false,
+ * using the given error message.
+ * This function is exported by this module.
+ */
 function assert(condition, message) {
     if (!condition)
         fail(message || 'Assertion failed');
 }
+/**
+ * Throws an error if the given function does not throw
+ * an error when executed.
+ * Can also provide a message string given to [[errorMessage]].
+ * @param block A function that should throw an error
+ * @param message The optional message string to match against
+ */
 function throws(block, message) {
     let success = true;
     try {
@@ -67,6 +106,24 @@ function throws(block, message) {
     }
     assert(success, message ? 'Was expecting error: ' + message : 'Should throw an error');
 }
+/**
+ * Throws an error if the provided values are not "equal".
+ * This has different meanings for different types of expected values:
+ * - If `expected` is an `Object`,
+ * `actual[key]` should "equal" `expected[key]` for each `key` in `expected`
+ * - If `expected` is an `Array`, the lengths should match
+ * and corresponding elements should be "equal"
+ * - If `expected` is a `Map`, the sizes should match and iterating
+ * should yield "equal" corresponding keys and values
+ * - If `expected` is a `Set`, `Array.from(actual)` should "equal" `Array.from(expected)`
+ * - If `expected` is an `ArrayBuffer`, the lengths should match and corresponding
+ * bytes should be "equal"
+ * - If `expected` is a `Function`, the names should be equal
+ * - If `expected` has an `equals()` method, that is used
+ * - Otherwise, `===` is used
+ * @param actual
+ * @param expected
+ */
 function equal(actual, expected) {
     const error = () => new RangeError('Expected ' + util_inspect_1.inspect(expected) + ' but got ' + util_inspect_1.inspect(actual));
     if (expected) {
@@ -205,27 +262,24 @@ function equal(actual, expected) {
             throw error();
     }
 }
+/**
+ * Throws an error if the given value is not an error
+ * or its message doesn't start with the given message string
+ * @param err The error value to test
+ * @param message The string that the error message should start with
+ */
 function errorMessage(err, message) {
     instanceOf(message, String);
     assert(err !== null && err.message.startsWith(message), 'Message "' + (err ? err.message : 'No error thrown') + '" does not start with "' + message + '"');
 }
 //tslint:disable-next-line:prefer-object-spread
 exports.default = Object.assign(assert, {
-    //Assert that the instance is an instance of the constructor, or at least one of the constructors, or a subclass
     instanceOf,
-    //Assert that a number is an integer (within the +/-2^53 that can be represented precisely in a double)
     integer,
-    //Assert that a number is between the specified values, with an optional message
     between,
-    //Assert that a number fits in an unsigned byte
     byteUnsignedInteger,
-    //Throw an error
     fail,
-    //Assert that the execution of a function throws an error, and that the error message matches the specified one
     throws,
-    //Assert that two values are "equal"
-    //What this means depends a lot on the type of the expected value
     equal,
-    //Assert that an error's message begins with the specified text
     errorMessage
 });

dist/lib/bit-math.d.ts

@@ -1,2 +1,10 @@
+/**
+ * Efficiently computes `Math.floor(n / 8)`
+ * @param n The number in question
+ */
 export declare function dividedByEight(n: number): number;
+/**
+ * Efficiently computes `n % 8`
+ * @param n The number in question
+ */
 export declare function modEight(n: number): number;

dist/lib/bit-math.js

@@ -1,10 +1,18 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
+/**
+ * Efficiently computes `Math.floor(n / 8)`
+ * @param n The number in question
+ */
 function dividedByEight(n) {
-    return n >>> 3; //efficiently divide by 8
+    return n >>> 3;
 }
 exports.dividedByEight = dividedByEight;
+/**
+ * Efficiently computes `n % 8`
+ * @param n The number in question
+ */
 function modEight(n) {
-    return n & 0b111; //efficiently mod 8
+    return n & 0b111;
 }
 exports.modEight = modEight;

dist/lib/buffer-stream.d.ts

@@ -3,8 +3,8 @@ import GrowableBuffer from './growable-buffer';
 import { Readable } from 'stream';
 /**
  * A class for creating a readable stream
- * out of an [ArrayBuffer]{@link external:ArrayBuffer}
- * or a {@link GrowableBuffer}.
+ * out of an `ArrayBuffer`
+ * or a [[GrowableBuffer]].
  * When dealing with very large buffers,
  * this allows chunks to be sent as they are requested
  * rather than stuffing the whole buffer into the stream at once.
@@ -16,13 +16,13 @@ export default class BufferStream extends Readable {
     private readonly end;
     private offset;
     /**
-     * @param {external:ArrayBuffer|GrowableBuffer} buffer
+     * @param buffer
      * The buffer whose data to use.
-     * If a {@link GrowableBuffer} is used, only the
+     * If a [[GrowableBuffer]] is used, only the
      * occupied portion will be written by the stream.
-     * Future additions to the {@link GrowableBuffer}
+     * Future additions to the [[GrowableBuffer]]
      * will not be written.
-     * If bytes inside the [ArrayBuffer]{@link external:ArrayBuffer}
+     * If bytes inside the `ArrayBuffer`
      * or occupied portion are changed, behavior is undefined.
      */
     constructor(buffer: ArrayBuffer | GrowableBuffer);

dist/lib/buffer-stream.js

@@ -5,8 +5,8 @@ const growable_buffer_1 = require("./growable-buffer");
 const stream_1 = require("stream");
 /**
  * A class for creating a readable stream
- * out of an [ArrayBuffer]{@link external:ArrayBuffer}
- * or a {@link GrowableBuffer}.
+ * out of an `ArrayBuffer`
+ * or a [[GrowableBuffer]].
  * When dealing with very large buffers,
  * this allows chunks to be sent as they are requested
  * rather than stuffing the whole buffer into the stream at once.
@@ -15,13 +15,13 @@ const stream_1 = require("stream");
  */
 class BufferStream extends stream_1.Readable {
     /**
-     * @param {external:ArrayBuffer|GrowableBuffer} buffer
+     * @param buffer
      * The buffer whose data to use.
-     * If a {@link GrowableBuffer} is used, only the
+     * If a [[GrowableBuffer]] is used, only the
      * occupied portion will be written by the stream.
-     * Future additions to the {@link GrowableBuffer}
+     * Future additions to the [[GrowableBuffer]]
      * will not be written.
-     * If bytes inside the [ArrayBuffer]{@link external:ArrayBuffer}
+     * If bytes inside the `ArrayBuffer`
      * or occupied portion are changed, behavior is undefined.
      */
     constructor(buffer) {

dist/lib/buffer-string.d.ts

@@ -1,4 +1,27 @@
+/**
+ * Converts UTF-8 bytes to a JavaScript string.
+ * The inverse of [[fromString]].
+ * @param buffer The binary data to convert
+ */
 export declare function toString(buffer: Uint8Array): string;
+/**
+ * Converts a JavaScript string to UTF-8 bytes.
+ * The inverse of [[toString]].
+ * @param str The string to convert
+ */
 export declare function fromString(str: string): ArrayBuffer;
+/**
+ * Converts bytes to a JavaScript string where
+ * each character corresponds to one byte.
+ * Like [[toString]] but works with bytes
+ * that are invalid UTF-8.
+ * Mainly used for using `ArrayBuffer`s as keys in maps.
+ * @param buffer The binary data to convert
+ */
 export declare function toBinaryString(buffer: ArrayBuffer): string;
+/**
+ * Converts a string generated by [[toBinaryString]]
+ * back into the bytes that generated it
+ * @param str The string to convert
+ */
 export declare function fromBinaryString(str: string): ArrayBuffer;

dist/lib/buffer-string.js

@@ -4,7 +4,11 @@ const assert_1 = require("./assert");
 const growable_buffer_1 = require("./growable-buffer");
 //Arbitrarily set; fairly low to be safe
 const MAX_ARGUMENTS_LENGTH = 0x1000;
-//Convert bytes to a UTF-8 string
+/**
+ * Converts UTF-8 bytes to a JavaScript string.
+ * The inverse of [[fromString]].
+ * @param buffer The binary data to convert
+ */
 function toString(buffer) {
     assert_1.default.instanceOf(buffer, Uint8Array);
     //Taken from https://github.com/feross/buffer/blob/da8a677bdb746ed9d6dae42ee1eaf236aad32ccb/index.js#L917-L988
@@ -75,6 +79,11 @@ function toString(buffer) {
     return str;
 }
 exports.toString = toString;
+/**
+ * Converts a JavaScript string to UTF-8 bytes.
+ * The inverse of [[toString]].
+ * @param str The string to convert
+ */
 //Convert a string to UTF-8 bytes
 function fromString(str) {
     assert_1.default.instanceOf(str, String);
@@ -85,30 +94,39 @@ function fromString(str) {
         if (charcode < 0x80)
             utf8.add(charcode);
         else if (charcode < 0x800) {
-            utf8.add(0xc0 | (charcode >> 6));
-            utf8.add(0x80 | (charcode & 0x3f));
+            utf8
+                .add(0xc0 | (charcode >> 6))
+                .add(0x80 | (charcode & 0x3f));
         }
         else {
             /*istanbul ignore else*/
             if (charcode < 0xd800 || charcode >= 0xe000) {
-                utf8.add(0xe0 | (charcode >> 12));
-                utf8.add(0x80 | ((charcode >> 6) & 0x3f));
-                utf8.add(0x80 | (charcode & 0x3f));
+                utf8
+                    .add(0xe0 | (charcode >> 12))
+                    .add(0x80 | ((charcode >> 6) & 0x3f))
+                    .add(0x80 | (charcode & 0x3f));
             }
             else {
                 charcode = 0x10000 + (((charcode & 0x3ff) << 10) | (charcode & 0x3ff));
-                utf8.add(0xf0 | (charcode >> 18));
-                utf8.add(0x80 | ((charcode >> 12) & 0x3f));
-                utf8.add(0x80 | ((charcode >> 6) & 0x3f));
-                utf8.add(0x80 | (charcode & 0x3f));
+                utf8
+                    .add(0xf0 | (charcode >> 18))
+                    .add(0x80 | ((charcode >> 12) & 0x3f))
+                    .add(0x80 | ((charcode >> 6) & 0x3f))
+                    .add(0x80 | (charcode & 0x3f));
             }
         }
     }
     return utf8.toBuffer();
 }
 exports.fromString = fromString;
-//Convert bytes to a string where each character represents one byte
-//Used for representing ArrayBuffers as keys in maps
+/**
+ * Converts bytes to a JavaScript string where
+ * each character corresponds to one byte.
+ * Like [[toString]] but works with bytes
+ * that are invalid UTF-8.
+ * Mainly used for using `ArrayBuffer`s as keys in maps.
+ * @param buffer The binary data to convert
+ */
 function toBinaryString(buffer) {
     assert_1.default.instanceOf(buffer, ArrayBuffer);
     let str = '';
@@ -119,7 +137,11 @@ function toBinaryString(buffer) {
     return str;
 }
 exports.toBinaryString = toBinaryString;
-//Convert a string generated by toBinaryString() back into bytes
+/**
+ * Converts a string generated by [[toBinaryString]]
+ * back into the bytes that generated it
+ * @param str The string to convert
+ */
 function fromBinaryString(str) {
     assert_1.default.instanceOf(str, String);
     const buffer = new ArrayBuffer(str.length);

dist/lib/constants.d.ts

@@ -1 +1,5 @@
+/**
+ * Type byte indicating what follows is a `flexInt` containing the location of the type.
+ * The number is a negative offset from this type byte to the true location.
+ */
 export declare const REPEATED_TYPE = 255;

dist/lib/constants.js

@@ -1,5 +1,7 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-//Type byte indicating what follows is a FlexInt containing the location of the type
-//The number is a negative offset from this type byte to the true location
+/**
+ * Type byte indicating what follows is a `flexInt` containing the location of the type.
+ * The number is a negative offset from this type byte to the true location.
+ */
 exports.REPEATED_TYPE = 0xFF;

dist/lib/constructor-registry.d.ts

@@ -1,16 +1,18 @@
+/**
+ * A value that acts as a constructor
+ */
 export interface Newable {
     new (): object;
 }
+/**
+ * A function that acts as a constructor
+ */
 export declare type Constructor = Function & Newable;
-/** @function
- * @name get
- * @desc Gets a constructor function
- * with the specified name. Multiple
- * invocations of this function with
+/**
+ * Gets a constructor function with the specified name.
+ * Multiple invocations of this function with
  * the same name produce the same function.
- * @param {Type} constructorName The name of the constructor
- * @return {constructor} A function that can be used
- * as a constructor and has the desired name
- * @private
+ * @param constructorName The name of the resulting constructor
+ * @return A function that can be used as a constructor and has the desired name
  */
 export declare function get(constructorName: string): Constructor;