Improve diff documentation

Author: jeskew

packages/crypto-ie11-detection/lib/CryptoOperation.ts

@@ -1,5 +1,11 @@
 import {Key} from "./Key";
 
+/**
+ * Represents a cryptographic operation that has been instantiated but not
+ * necessarily fed all data or finalized.
+ *
+ * @see https://msdn.microsoft.com/en-us/library/dn280996(v=vs.85).aspx
+ */
 export interface CryptoOperation {
     readonly algorithm: string;
     readonly key: Key;

packages/crypto-ie11-detection/lib/Key.ts

@@ -1,3 +1,9 @@
+/**
+ * The result of a successful KeyOperation.
+ *
+ * @see {KeyOperation}
+ * @see https://msdn.microsoft.com/en-us/library/dn302313(v=vs.85).aspx
+ */
 export interface Key {
     readonly algorithm: string;
     readonly extractable: boolean;

packages/crypto-ie11-detection/lib/KeyOperation.ts

@@ -1,5 +1,11 @@
 import {Key} from "./Key";
 
+/**
+ * Represents the return of a key-related operation that may or may not have
+ * been completed.
+ *
+ * @see https://msdn.microsoft.com/en-us/library/dn302314(v=vs.85).aspx
+ */
 export interface KeyOperation {
     oncomplete: (event: Event) => void;
     onerror: (event: Event) => void;

packages/crypto-ie11-detection/lib/MsSubtleCrypto.ts

@@ -19,6 +19,14 @@ export interface HmacAlgorithm {
 
 export type SigningAlgorithm = HmacAlgorithm;
 
+/**
+ * Represent ths SubtleCrypto interface as implemented in Internet Explorer 11.
+ * This implementation was based on an earlier version of the WebCrypto API and
+ * differs from the `window.crypto.subtle` object exposed in Chrome, Safari,
+ * Firefox, and MS Edge.
+ *
+ * @see https://msdn.microsoft.com/en-us/library/dn302325(v=vs.85).aspx
+ */
 export interface MsSubtleCrypto {
     decrypt(
         algorithm: Ie11EncryptionAlgorithm,

packages/crypto-ie11-detection/lib/MsWindow.ts

@@ -1,7 +1,7 @@
 import {isNativeCode} from './isNativeCode';
 import {MsSubtleCrypto} from "./MsSubtleCrypto";
 
-export type SubtleCryptoMethod = 'decrypt'|'digest'|'encrypt'|'exportKey'|'generateKey'|'importKey'|'sign'|'verify';
+type SubtleCryptoMethod = 'decrypt'|'digest'|'encrypt'|'exportKey'|'generateKey'|'importKey'|'sign'|'verify';
 
 const msSubtleCryptoMethods: Array<SubtleCryptoMethod> = [
     'decrypt',
@@ -14,11 +14,18 @@ const msSubtleCryptoMethods: Array<SubtleCryptoMethod> = [
     'verify',
 ];
 
+/**
+ * The value accessible as `window.msCrypto` in Internet Explorer 11.
+ */
 export interface MsCrypto {
     getRandomValues: (toFill: Uint8Array) => void;
     subtle: MsSubtleCrypto;
 }
 
+/**
+ * The `window` object in Internet Explorer 11. This interface does not
+ * exhaustively document the prefixed features of `window` in IE11.
+ */
 export interface MsWindow extends Window {
     MSInputMethodContext: any;
     msCrypto: MsCrypto;

packages/crypto-ie11-detection/lib/isNativeCode.ts

@@ -1,5 +1,11 @@
 const nativeCodeRegex = /\[native code]/;
 
+/**
+ * A best-effort check to see if a function is user-defined or provided by the
+ * browser. This is a heuristic rather than something 100% accurate.
+ *
+ * @internal
+ */
 export function isNativeCode(func: Function): boolean {
     try {
         if (nativeCodeRegex.test(Function.prototype.toString.call(func))) {

packages/crypto-ie11-detection/tsconfig.json

@@ -4,6 +4,7 @@
         "target": "es5",
         "strict": true,
         "sourceMap": true,
-        "declaration": true
+        "declaration": true,
+        "stripInternal": true
     }
 }

packages/crypto-random-source-browser/lib/ie11RandomValues.ts

@@ -1,5 +1,9 @@
 import {MsWindow} from '@aws/crypto-ie11-detection';
+import {randomValues as IRandomValues} from '@aws/types';
 
+/**
+ * @implements {IRandomValues}
+ */
 export function randomValues(byteLength: number): Promise<Uint8Array> {
     return new Promise(resolve => {
         const randomBytes = new Uint8Array(byteLength);

packages/crypto-random-source-browser/lib/jsRandomValues.ts

@@ -5,7 +5,11 @@ import {
     startCollectors,
     stopCollectors,
 } from '@aws/crypto-sjcl-random';
+import {randomValues as IRandomValues} from '@aws/types';
 
+/**
+ * @implements {IRandomValues}
+ */
 export function randomValues(byteLength: number): Promise<Uint8Array> {
     return new Promise((resolve, reject) => {
         if (!isReady()) {

packages/crypto-random-source-browser/lib/webCryptoRandomValues.ts

@@ -1,3 +1,8 @@
+import {randomValues as IRandomValues} from '@aws/types';
+
+/**
+ * @implements {IRandomValues}
+ */
 export function randomValues(byteLength: number): Promise<Uint8Array> {
     return new Promise(resolve => {
         const randomBytes = new Uint8Array(byteLength);

packages/crypto-random-source-browser/package.json

@@ -13,7 +13,8 @@
     "@aws/crypto-ie11-detection": "^0.0.1",
     "@aws/crypto-sjcl-random": "^0.0.1",
     "@aws/crypto-sjcl-codecArrayBuffer": "^0.0.1",
-    "@aws/crypto-supports-webCrypto": "^0.0.1"
+    "@aws/crypto-supports-webCrypto": "^0.0.1",
+    "@aws/types": "^0.0.1"
   },
   "devDependencies": {
     "@types/jest": "^19.2.2",

packages/crypto-random-source-node/index.ts

@@ -1,5 +1,9 @@
 import {randomBytes} from 'crypto';
+import {randomValues as IRandomValues} from '@aws/types';
 
+/**
+ * @implements {IRandomValues}
+ */
 export function randomValues(byteLength: number): Promise<Uint8Array> {
     return new Promise<Buffer>((resolve, reject) => {
         randomBytes(byteLength, (err: Error, buf: Buffer) => {

packages/crypto-random-source-node/package.json

@@ -9,6 +9,9 @@
   },
   "author": "[email protected]",
   "license": "UNLICENSED",
+  "dependencies": {
+    "@aws/types": "^0.0.1"
+  },
   "devDependencies": {
     "@types/jest": "^19.2.2",
     "@types/node": "^7.0.12",

packages/crypto-random-source-universal/index.ts

@@ -5,7 +5,11 @@ import {
 import {
     randomValues as nodeRandomValues
 } from '@aws/crypto-random-source-node';
+import {randomValues as IRandomValues} from '@aws/types';
 
+/**
+ * @implements {IRandomValues}
+ */
 export function randomValues(byteLength: number): Promise<Uint8Array> {
     if (isNode()) {
         return nodeRandomValues(byteLength);

packages/crypto-random-source-universal/package.json

@@ -12,7 +12,8 @@
   "dependencies": {
     "@aws/crypto-random-source-browser": "^0.0.1",
     "@aws/crypto-random-source-node": "^0.0.1",
-    "@aws/is-node": "^0.0.1"
+    "@aws/is-node": "^0.0.1",
+    "@aws/types": "^0.0.1"
   },
   "devDependencies": {
     "@types/jest": "^19.2.2",

packages/crypto-supports-webCrypto/lib/isNativeCode.ts

@@ -1,5 +1,11 @@
 const nativeCodeRegex = /\[native code]/;
 
+/**
+ * A best-effort check to see if a function is user-defined or provided by the
+ * browser. This is a heuristic rather than something 100% accurate.
+ *
+ * @internal
+ */
 export function isNativeCode(func: Function): boolean {
     try {
         if (nativeCodeRegex.test(Function.prototype.toString.call(func))) {

packages/is-node/index.ts

@@ -1,3 +1,9 @@
+/**
+ * Detects if the function is invoked within a Node.JS environment based on the
+ * presence of `process` global variable and its `toString` output.
+ */
 export function isNode(): boolean {
-    return Object.prototype.toString.call(typeof process !== 'undefined' ? process : 0) === '[object process]';
+    return Object.prototype.toString.call(
+        typeof process !== 'undefined' ? process : 0
+    ) === '[object process]';
 }

packages/types/crypto.ts

@@ -1,14 +1,41 @@
 export type SourceData = string|ArrayBuffer|ArrayBufferView;
 
+/**
+ * An object that provides a hash of data provided in chunks to `update`. The
+ * hash may be performed incrementally as chunks are received or all at once
+ * when the hash is finalized, depending on the underlying implementation.
+ */
 export interface Hash {
+    /**
+     * Adds a chunk of data to the hash. If a buffer is provided, the `encoding`
+     * argument will be ignored. If a string is provided without a specified
+     * encoding, implementations must assume UTF-8 encoding.
+     *
+     * Not all encodings are supported on all platforms, though all must support
+     * UTF-8.
+     */
     update(toHash: SourceData, encoding?: 'utf8'|'ascii'|'latin1'): void;
+
+    /**
+     * Finalizes the hash and provides a promise that will be fulfilled with the
+     * raw bytes of the calculated hash.
+     */
     digest(): Promise<Uint8Array>;
 }
 
+/**
+ * A constructor for a hash that may be used to calculate an HMAC. Implementing
+ * classes should not directly hold the provided key in memory beyond the
+ * lexical scope of the constructor.
+ */
 export interface HashConstructor {
     new (secret?: SourceData): Hash;
 }
 
+/**
+ * A function that returns a promise fulfilled with bytes from a
+ * cryptographically secure pseudorandom number generator.
+ */
 export interface randomValues {
     (byteLength: number): Promise<Uint8Array>;
 }