Merge branch 'development' into feature/deployer-improvements

4 files changed, 62 insertions, 39 deletions

diff --git a/packages/sol-cov/README.md b/packages/sol-cov/README.md
index 6a98346f9..5591b9731 100644
--- a/packages/sol-cov/README.md
+++ b/packages/sol-cov/README.md
@@ -2,41 +2,26 @@
 
 A Solidity code coverage tool.
 
+### Read the [Documentation](0xproject.com/docs/sol-cov).
+
 ## Installation
 
 ```bash
-yarn add -D @0xproject/sol-cov
+yarn add @0xproject/sol-cov
 ```
 
-## Usage
-
-Sol-cov uses transaction traces in order to figure out which lines of Solidity source code have been covered by your tests. In order for it to gather these traces, you must add the `CoverageSubprovider` to the [ProviderEngine](https://github.com/MetaMask/provider-engine) instance you use when running your Solidity tests. If you're unfamiliar with ProviderEngine, please read the [Web3 Provider explained](https://0xproject.com/wiki#Web3-Provider-Explained) wiki article.
+**Import**
 
-The CoverageSubprovider eavesdrops on the `eth_sendTransaction` and `eth_call` RPC calls and collects traces after each call using `debug_traceTransaction`. `eth_call`'s' don't generate traces - so we take a snapshot, re-submit it as a transaction, get the trace and then revert the snapshot.
-
-```typescript
+```javascript
 import { CoverageSubprovider } from '@0xproject/sol-cov';
-
-const provider = new ProviderEngine();
-
-const artifactsPath = 'src/artifacts';
-const contractsPath = 'src/contracts';
-const networkId = 50;
-// Some calls might not have `from` address specified. Nevertheless - transactions need to be submitted from an address with at least some funds. defaultFromAddress is the address that will be used to submit those calls as transactions from.
-const defaultFromAddress = '0x5409ed021d9299bf6814279a6a1411a7e866a631';
-const coverageSubprovider = new CoverageSubprovider(artifactsPath, contractsPath, networkId, defaultFromAddress);
-
-provider.addProvider(coverageSubprovider);
 ```
 
-After your test suite is complete (e.g global `after` hook), you'll need to call:
+or
 
-```typescript
-await coverageSubprovider.writeCoverageAsync();
+```javascript
+var CoverageSubprovider = require('@0xproject/sol-cov').CoverageSubprovider;
 ```
 
-This will create a `coverage.json` file in the `coverage` directory. This file has an [Istanbul format](https://github.com/gotwarlost/istanbul/blob/master/coverage.json.md) - so you can use any of the existing Instanbul reporters.
-
 ## Contributing
 
 We strongly encourage the community to help us make improvements. To report bugs within this package, please create an issue in this repository.
diff --git a/packages/sol-cov/package.json b/packages/sol-cov/package.json
index 3292921fb..106c47d13 100644
--- a/packages/sol-cov/package.json
+++ b/packages/sol-cov/package.json
@@ -13,7 +13,20 @@
         "test:circleci": "yarn test:coverage",
         "run_mocha": "mocha lib/test/**/*_test.js",
         "clean": "shx rm -rf lib scripts",
-        "build": "copyfiles 'test/fixtures/**/*' ./lib && tsc && copyfiles -u 3 './lib/src/monorepo_scripts/**/*' ./scripts"
+        "build": "copyfiles 'test/fixtures/**/*' ./lib && tsc && copyfiles -u 3 './lib/src/monorepo_scripts/**/*' ./scripts",
+        "docs:stage": "yarn build && node ./scripts/stage_docs.js",
+        "docs:json": "typedoc --excludePrivate --excludeExternals --target ES5 --json $JSON_FILE_PATH $PROJECT_FILES",
+        "upload_docs_json": "aws s3 cp generated_docs/index.json $S3_URL --profile 0xproject --grants read=uri=http://acs.amazonaws.com/groups/global/AllUsers --content-type application/json"
+    },
+    "config": {
+        "postpublish": {
+            "assets": [],
+            "docPublishConfigs": {
+                "extraFileIncludes": ["../subproviders/src/types.ts"],
+                "s3BucketPath": "s3://doc-jsons/sol-cov/",
+                "s3StagingBucketPath": "s3://staging-doc-jsons/sol-cov/"
+            }
+        }
     },
     "repository": {
         "type": "git",
@@ -53,6 +66,7 @@
         "shx": "^0.2.2",
         "sinon": "^4.0.0",
         "tslint": "5.8.0",
+        "typedoc": "0xProject/typedoc",
         "typescript": "2.7.1",
         "web3-typescript-typings": "^0.9.11"
     },
diff --git a/packages/sol-cov/src/coverage_subprovider.ts b/packages/sol-cov/src/coverage_subprovider.ts
index 71d90bba7..37682c45f 100644
--- a/packages/sol-cov/src/coverage_subprovider.ts
+++ b/packages/sol-cov/src/coverage_subprovider.ts
@@ -1,4 +1,4 @@
-import { Callback, NextCallback, Subprovider } from '@0xproject/subproviders';
+import { Callback, ErrorCallback, NextCallback, Subprovider } from '@0xproject/subproviders';
 import { promisify } from '@0xproject/utils';
 import * as _ from 'lodash';
 import { Lock } from 'semaphore-async-await';
@@ -12,18 +12,26 @@ interface MaybeFakeTxData extends Web3.TxData {
     isFakeTransaction?: boolean;
 }
 
-/*
- * This class implements the web3-provider-engine subprovider interface and collects traces of all transactions that were sent and all calls that were executed.
- * Because there is no notion of call trace in the rpc - we collect them in rather non-obvious/hacky way.
- * On each call - we create a snapshot, execute the call as a transaction, get the trace, revert the snapshot.
- * That allows us to not influence the test behaviour.
- * Source: https://github.com/MetaMask/provider-engine/blob/master/subproviders/subprovider.js
+// Because there is no notion of a call trace in the Ethereum rpc - we collect them in a rather non-obvious/hacky way.
+// On each call - we create a snapshot, execute the call as a transaction, get the trace, revert the snapshot.
+// That allows us to avoid influencing test behaviour.
+
+/**
+ * This class implements the [web3-provider-engine](https://github.com/MetaMask/provider-engine) subprovider interface.
+ * It collects traces of all transactions that were sent and all calls that were executed through JSON RPC.
  */
 export class CoverageSubprovider extends Subprovider {
     // Lock is used to not accept normal transactions while doing call/snapshot magic because they'll be reverted later otherwise
     private _lock: Lock;
     private _coverageManager: CoverageManager;
     private _defaultFromAddress: string;
+    /**
+     * Instantiates a CoverageSubprovider instance
+     * @param artifactsPath Path to the smart contract artifacts
+     * @param sourcesPath Path to the smart contract source files
+     * @param networkId network id
+     * @param defaultFromAddress default from address to use when sending transactions
+     */
     constructor(artifactsPath: string, sourcesPath: string, networkId: number, defaultFromAddress: string) {
         super();
         this._lock = new Lock();
@@ -35,11 +43,22 @@ export class CoverageSubprovider extends Subprovider {
             this._getContractCodeAsync.bind(this),
         );
     }
-    public handleRequest(
-        payload: Web3.JSONRPCRequestPayload,
-        next: NextCallback,
-        end: (err: Error | null, result: any) => void,
-    ) {
+    /**
+     * Write the test coverage results to a file in Istanbul format.
+     */
+    public async writeCoverageAsync(): Promise<void> {
+        await this._coverageManager.writeCoverageAsync();
+    }
+    /**
+     * This method conforms to the web3-provider-engine interface.
+     * It is called internally by the ProviderEngine when it is this subproviders
+     * turn to handle a JSON RPC request.
+     * @param payload JSON RPC payload
+     * @param next Callback to call if this subprovider decides not to handle the request
+     * @param end Callback to call if subprovider handled the request and wants to pass back the request.
+     */
+    // tslint:disable-next-line:prefer-function-over-method
+    public handleRequest(payload: Web3.JSONRPCRequestPayload, next: NextCallback, end: ErrorCallback) {
         switch (payload.method) {
             case 'eth_sendTransaction':
                 const txData = payload.params[0];
@@ -57,9 +76,6 @@ export class CoverageSubprovider extends Subprovider {
                 return;
         }
     }
-    public async writeCoverageAsync(): Promise<void> {
-        await this._coverageManager.writeCoverageAsync();
-    }
     private async _onTransactionSentAsync(
         txData: MaybeFakeTxData,
         err: Error | null,
diff --git a/packages/sol-cov/src/monorepo_scripts/stage_docs.ts b/packages/sol-cov/src/monorepo_scripts/stage_docs.ts
new file mode 100644
index 000000000..e732ac8eb
--- /dev/null
+++ b/packages/sol-cov/src/monorepo_scripts/stage_docs.ts
@@ -0,0 +1,8 @@
+import { postpublishUtils } from '@0xproject/monorepo-scripts';
+
+import * as packageJSON from '../package.json';
+import * as tsConfigJSON from '../tsconfig.json';
+
+const cwd = `${__dirname}/..`;
+// tslint:disable-next-line:no-floating-promises
+postpublishUtils.publishDocsToStagingAsync(packageJSON, tsConfigJSON, cwd);