Improve sol-cov docs

2 files changed, 78 insertions, 6 deletions

diff --git a/packages/website/md/docs/sol_cov/usage.md b/packages/website/md/docs/sol_cov/usage.md
index 63a88f595..59638f611 100644
--- a/packages/website/md/docs/sol_cov/usage.md
+++ b/packages/website/md/docs/sol_cov/usage.md
@@ -2,8 +2,47 @@ Sol-cov uses transaction traces in order to figure out which lines of Solidity s
 
 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.
 
+Coverage subprovider needs some info about your contracts (`srcMap`, `bytecode`). It gets that info from your project's artifacts. Some frameworks have their own artifact format. Some artifact formats don't actually contain all the neccessary data.
+
+In order to use `CoverageSubprovider` with your favorite framework you need to pass an `artifactsAdapter` to it.
+
+### Sol-compiler
+
+If you are generating your artifacts with [@0xproject/sol-compiler](LINK) you can use the `SolCompilerArtifactsAdapter` we've implemented for you.
+
+```typescript
+<<<<<<< HEAD
+import { CoverageSubprovider } from '@0xproject/sol-cov';
+=======
+import { SolCompilerArtifactsAdapter } from '@0xproject/sol-cov';
+const artifactsPath = 'src/artifacts';
+const contractsPath = 'src/contracts';
+const artifactsAdapter = new SolCompilerArtifactsAdapter(artifactsPath, contractsPath);
+```
+
+### Truffle
+
+If your project is using [Truffle](LINK), we've written a `TruffleArtifactsAdapter`for you.
+
+```typescript
+import { TruffleArtifactAdapter } from '@0xproject/sol-cov';
+const contractsPath = 'src/contracts';
+const artifactAdapter = new TruffleArtifactAdapter(contractsDir);
+```
+
+Because truffle artifacts don't have all the data we need - we actually will recompile your contracts under the hood. That's why you don't need to pass an `artifactsPath`.
+
+### Other framework/toolset
+
+You'll need to write your own artifacts adapter. It should extend `AbstractArtifactsAdapter`.
+Look at the code of the two adapters above for examples.
+
+### Usage
+
 ```typescript
 import { CoverageSubprovider } from '@0xproject/sol-cov';
+import ProviderEngine = require('web3-provider-engine');
+>>>>>>> Improve sol-cov docs
 
 const provider = new ProviderEngine();
 
@@ -12,15 +51,20 @@ 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';
+<<<<<<< HEAD
 const coverageSubprovider = new CoverageSubprovider(artifactsPath, contractsPath, defaultFromAddress);
+=======
+const isVerbose = true;
+const coverageSubprovider = new CoverageSubprovider(artifactsAdapter, defaultFromAddress, isVerbose);
+>>>>>>> Improve sol-cov docs
 
 provider.addProvider(coverageSubprovider);
 ```
 
-After your test suite is complete (e.g global `after` hook), you'll need to call:
+After your test suite is complete (e.g in the Mocha global `after` hook), you'll need to call:
 
 ```typescript
 await coverageSubprovider.writeCoverageAsync();
 ```
 
-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.
+This will create a `coverage.json` file in a `coverage` directory. This file has an [Istanbul format](https://github.com/gotwarlost/istanbul/blob/master/coverage.json.md) - so you can use it with any of the existing Istanbul reporters.
diff --git a/packages/website/ts/containers/sol_cov_documentation.ts b/packages/website/ts/containers/sol_cov_documentation.ts
index 58755c1e0..bc05b6854 100644
--- a/packages/website/ts/containers/sol_cov_documentation.ts
+++ b/packages/website/ts/containers/sol_cov_documentation.ts
@@ -22,6 +22,9 @@ const docSections = {
     installation: 'installation',
     usage: 'usage',
     coverageSubprovider: 'coverageSubprovider',
+    abstractArtifactAdapter: 'abstractArtifactAdapter',
+    solCompilerArtifactAdapter: 'solCompilerArtifactAdapter',
+    truffleArtifactAdapter: 'truffleArtifactAdapter',
     types: docConstants.TYPES_SECTION_NAME,
 };
 
@@ -34,7 +37,10 @@ const docsInfoConfig: DocsInfoConfig = {
         introduction: [docSections.introduction],
         install: [docSections.installation],
         usage: [docSections.usage],
-        coverageSubprovider: [docSections.coverageSubprovider],
+        'coverage-subprovider': [docSections.coverageSubprovider],
+        'abstract-artifact-adapter': [docSections.abstractArtifactAdapter],
+        'sol-compiler-artifact-adapter': [docSections.solCompilerArtifactAdapter],
+        'truffle-artifact-adapter': [docSections.truffleArtifactAdapter],
         types: [docSections.types],
     },
     sectionNameToMarkdown: {
@@ -44,18 +50,40 @@ const docsInfoConfig: DocsInfoConfig = {
     },
     sectionNameToModulePath: {
         [docSections.coverageSubprovider]: ['"sol-cov/src/coverage_subprovider"'],
+        [docSections.abstractArtifactAdapter]: ['"sol-cov/src/artifact_adapters/abstract_artifact_adapter"'],
+        [docSections.solCompilerArtifactAdapter]: ['"sol-cov/src/artifact_adapters/sol_compiler_artifact_adapter"'],
+        [docSections.truffleArtifactAdapter]: ['"sol-cov/src/artifact_adapters/truffle_artifact_adapter"'],
         [docSections.types]: ['"subproviders/src/types"', '"types/src/index"'],
     },
     menuSubsectionToVersionWhenIntroduced: {},
     sections: docSections,
-    visibleConstructors: [docSections.coverageSubprovider],
+    visibleConstructors: [
+        docSections.coverageSubprovider,
+        docSections.abstractArtifactAdapter,
+        docSections.solCompilerArtifactAdapter,
+        docSections.truffleArtifactAdapter,
+    ],
     typeConfigs: {
         // Note: This needs to be kept in sync with the types exported in index.ts. Unfortunately there is
         // currently no way to extract the re-exported types from index.ts via TypeDoc :(
-        publicTypes: ['NextCallback', 'OnNextCompleted', 'ErrorCallback', 'JSONRPCRequestPayload'],
+        publicTypes: [
+            'JSONRPCRequestPayload',
+            'NextCallback',
+            'ErrorCallback',
+            'AbstractArtifactAdapter',
+            'CoverageSubprovider',
+            'TruffleArtifactAdapter',
+            'SolCompilerArtifactAdapter',
+            'ContractData',
+        ],
         typeNameToExternalLink: {},
         typeNameToPrefix: {},
-        typeNameToDocSection: {},
+        typeNameToDocSection: {
+            AbstractArtifactAdapter: docSections.abstractArtifactAdapter,
+            CoverageSubprovider: docSections.coverageSubprovider,
+            TruffleArtifactAdapter: docSections.truffleArtifactAdapter,
+            SolCompilerArtifactAdapter: docSections.solCompilerArtifactAdapter,
+        },
     },
 };
 const docsInfo = new DocsInfo(docsInfoConfig);