Merge pull request #173 from bigchaindb/fix/documentation

Readme & dev updates
bigchaindb · May 14, 2018 · 5c106a2 · 5c106a2
2 parents 4570b24 + 81ef597
commit 5c106a2
Show file tree

Hide file tree

Showing 14 changed files with 415 additions and 195 deletions.
diff --git a/.babelrc b/.babelrc
@@ -1,10 +1,11 @@
 {
-    "presets": ["env"],
-
+    "presets": [
+        "env"
+    ],
     "plugins": [
         "transform-export-extensions",
         "transform-object-assign",
         "transform-object-rest-spread"
     ],
-    "sourceMaps": true,
-}
+    "sourceMaps": true
+}
diff --git a/API.md b/API.md
diff --git a/README.md b/README.md
@@ -1,6 +1,6 @@
 # [![js-bigchaindb-driver](media/repo-banner@2x.png)](https://www.bigchaindb.com)
 
-> Official JavaScript driver for [BigchainDB](https://github.com/bigchaindb/bigchaindb) with some naive helpers to get you on your way making transactions in Node.js and the browser.
+> Official JavaScript driver for [BigchainDB](https://github.com/bigchaindb/bigchaindb) to create transactions in Node.js and the browser.
 
 [![Join the chat at https://gitter.im/bigchaindb/js-bigchaindb-driver](https://badges.gitter.im/bigchaindb/js-bigchaindb-driver.svg)](https://gitter.im/bigchaindb/js-bigchaindb-driver?utm_source=badge&utm_medium=badge&utm_campaign=pr-badge&utm_content=badge)
 [![npm](https://img.shields.io/npm/v/bigchaindb-driver.svg)](https://www.npmjs.com/package/bigchaindb-driver)
@@ -9,44 +9,54 @@
 [![Build Status](https://travis-ci.org/bigchaindb/js-bigchaindb-driver.svg?branch=master)](https://travis-ci.org/bigchaindb/js-bigchaindb-driver)
 [![Greenkeeper badge](https://badges.greenkeeper.io/bigchaindb/js-bigchaindb-driver.svg)](https://greenkeeper.io/)
 
-- Documentation: https://docs.bigchaindb.com/projects/js-driver/en/latest/usage.html
+- [Main Documentation](https://docs.bigchaindb.com/projects/js-driver/en/latest/usage.html)
+- [Driver API reference](API.md)
 
 ## Compatibility
 
 | BigchainDB Server | BigchainDB JavaScript Driver |
 | ----------------- |------------------------------|
 | `0.10`            | `0.1.x`                      |
-| `1.0.0`        | `0.3.x`                      |
-| `1.3.x`        | `3.x.x`                      |
+| `1.0.0`           | `0.3.x`                      |
+| `1.3.x`           | `3.x.x`                      |
 | `>= 2.0.0`        | `4.x.x`                      |
 
 ## Breaking changes
 
 - **Version 4.0** of BigchainDB JavaScript Driver makes the driver compatible with BigchainDB 2.0. There are new functions for sending off transactions along with other changes. Check [older versions](https://docs.bigchaindb.com/projects/js-driver/en/latest/readme.html#features)
 - **Version 3.2** of BigchainDB JavaScript Driver introduces a new way of creating transfer transactions. Check [older versions](https://docs.bigchaindb.com/projects/js-driver/en/latest/readme.html#features)
 
+## Table of Contents
 
-## Contents
+  - [Installation and Usage](#installation-and-usage)
+     - [Example: Create a transaction](#example-create-a-transaction)
+     - [Browser usage](#browser-usage)
+  - [BigchainDB Documentation](#bigchaindb-documentation)
+  - [Speed Optimizations](#speed-optimizations)
+  - [Development](#development)
+  - [Authors](#authors)
+  - [License](#license)
 
-* [Installation and Usage with package managers (npm/yarn)](#installation-and-usage-with-package-managers-npmyarn)
-   * [Example: Create a transaction](#example-create-a-transaction)
-* [Use a pre-built image (browser only)](#use-a-pre-built-image-browser-only)
-* [Documentation](#bigchaindb-documentation)
-* [Authors](#authors)
-* [License](#license)
+---
 
-## Installation and Usage with package managers (npm/yarn)
+## Installation and Usage
 
 ```bash
 npm install bigchaindb-driver
 ```
 
+```js
+const driver = require('bigchaindb-driver')
+// or ES6+
+import driver from 'bigchaindb-driver'
+```
+
 ### Example: Create a transaction
 
 ```js
 const driver = require('bigchaindb-driver')
 
-// BigchainDB server instance or IPDB (e.g. https://test.ipdb.io/api/v1/)
+// BigchainDB server instance (e.g. https://test.bigchaindb.com/api/v1/)
 const API_PATH = 'http://localhost:9984/api/v1/'
 
 // Create a new keypair.
@@ -79,7 +89,7 @@ conn.postTransactionCommit(txSigned)
     .then(retrievedTx => console.log('Transaction', retrievedTx.id, 'successfully posted.'))
 ```
 
-## Use a pre-built image (browser only)
+### Browser usage
 
 ```html
 <!DOCTYPE html>
@@ -91,7 +101,7 @@ conn.postTransactionCommit(txSigned)
         <script src="https://unpkg.com/bigchaindb-driver@4.0.0/dist/browser/bigchaindb-driver.window.min.js"></script>
 
         <script>
-            // BigchainDB server instance or IPDB (e.g. https://test.ipdb.io/api/v1/)
+            // BigchainDB server instance (e.g. https://test.bigchaindb.com/api/v1/)
             const API_PATH = 'http://localhost:9984/api/v1/'
 
             // Create a new keypair.
@@ -139,6 +149,7 @@ conn.postTransactionCommit(txSigned)
 
 ## BigchainDB Documentation
 
+- [The Hitchhiker's Guide to BigchainDB](https://www.bigchaindb.com/developers/guide/)
 - [HTTP API Reference](https://docs.bigchaindb.com/projects/server/en/latest/http-client-server-api.html)
 - [The Transaction Model](https://docs.bigchaindb.com/projects/server/en/latest/data-models/transaction-model.html?highlight=crypto%20conditions)
 - [Inputs and Outputs](https://docs.bigchaindb.com/projects/server/en/latest/data-models/inputs-outputs.html)
@@ -152,6 +163,21 @@ This implementation plays "safe" by using JS-native (or downgradable) libraries
 * [chloride](https://github.com/dominictarr/chloride), or its underlying [sodium](https://github.com/paixaop/node-sodium) library
 * [node-sha3](https://github.com/phusion/node-sha3) -- **MAKE SURE** to use [steakknife's fork](https://github.com/steakknife/node-sha3) if [the FIPS 202 upgrade](https://github.com/phusion/node-sha3/pull/25) hasn't been merged (otherwise, you'll run into all kinds of hashing problems)
 
+## Development
+
+```js
+git clone git@github.com:bigchaindb/js-bigchaindb-driver.git
+cd js-bigchaindb-driver/
+
+npm i
+npm run dev
+```
+
+After updating source files in `src/`, make sure to update the API documentation. The following command will scan all source files and create the Markdown output into `./API.md`:
+
+```bash
+npm run doc
+```
 
 ## Authors
 

diff --git a/package.json b/package.json
@@ -13,21 +13,22 @@
   "main": "./dist/node/index.js",
   "browser": "./dist/browser/bigchaindb-driver.cjs2.min.js",
   "scripts": {
-    "lint": "./node_modules/.bin/eslint ./",
+    "lint": "eslint ./{src,test,examples}",
     "build": "npm run clean && npm run build:cjs && npm run build:dist",
     "build:bundle": "webpack",
     "build:cjs": "cross-env BABEL_ENV=cjs babel ./src -d dist/node",
     "build:dist": "cross-env NODE_ENV=production webpack -p",
+    "dev": "webpack -p -w",
     "clean": "rimraf dist/bundle dist/node",
     "test": "npm run lint && nyc ava test/ && npm run thanks && npm run report-coverage",
-    "testmine": "npm run lint && nyc ava test/integration/test_min*",
     "thanks": "cowsay Hi, thanks for your interest in BigchainDB. We appreciate your contribution!",
     "release": "./node_modules/release-it/bin/release-it.js --src.tagName='v%s' --github.release --npm.publish --non-interactive",
     "release-minor": "./node_modules/release-it/bin/release-it.js minor --src.tagName='v%s' --github.release --npm.publish --non-interactive",
     "release-major": "./node_modules/release-it/bin/release-it.js major --src.tagName='v%s' --github.release --npm.publish --non-interactive",
     "prepublishOnly": "npm run build",
     "precommit": "lint-staged",
-    "report-coverage": "nyc report --reporter=lcov > coverage.lcov && codecov"
+    "report-coverage": "nyc report --reporter=lcov > coverage.lcov && codecov",
+    "doc": "node ./node_modules/documentation/bin/documentation.js build src/index.js -f md -o API.md -g --markdown-toc"
   },
   "lint-staged": {
     "*.js": [
@@ -49,16 +50,17 @@
     "babel-preset-es2015-no-commonjs": "0.0.2",
     "babel-runtime": "^6.26.0",
     "cross-env": "^5.1.4",
+    "documentation": "^6.3.2",
     "eslint": "^4.19.1",
     "eslint-config-ascribe": "^3.0.5",
     "eslint-plugin-import": "^2.9.0",
     "husky": "^0.14.3",
     "lint-staged": "^7.0.0",
-    "sinon": "^5.0.0",
     "nyc": "^11.6.0",
     "release-it": "^7.2.1",
     "rimraf": "^2.6.2",
-    "webpack": "^4.4.1",
+    "sinon": "^5.0.0",
+    "webpack": "^4.8.3",
     "webpack-cli": "^2.0.13"
   },
   "dependencies": {
@@ -104,4 +106,4 @@
     ],
     "babel": "inherit"
   }
-}
+}
diff --git a/src/Ed25519Keypair.js b/src/Ed25519Keypair.js
@@ -3,7 +3,7 @@ import nacl from 'tweetnacl'
 
 /**
  * @public
- * @class Keypair Ed25519 keypair in base58 (as BigchainDB expects base58 keys)
+ * Ed25519 keypair in base58 (as BigchainDB expects base58 keys)
  * @type {Object}
  * @param {Buffer} [seed] A seed that will be used as a key derivation function
  * @property {string} publicKey

diff --git a/src/baseRequest.js b/src/baseRequest.js
@@ -3,14 +3,13 @@ import fetchPonyfill from 'fetch-ponyfill'
 import { vsprintf } from 'sprintf-js'
 
 import formatText from './format_text'
-
 import stringifyAsQueryParam from './stringify_as_query_param'
 
-
 const fetch = fetchPonyfill(Promise)
 
 
 /**
+ * @private
  * imported from https://github.com/bigchaindb/js-utility-belt/
  *
  * Global fetch wrapper that adds some basic error handling and ease of use enhancements.
@@ -24,14 +23,14 @@ const fetch = fetchPonyfill(Promise)
  * @param  {string}  url    Url to request. Can be specified as a sprintf format string (see
  *                          https://github.com/alexei/sprintf.js) that will be resolved using
  *                          `config.urlTemplateSpec`.
- * @param  {object}  config Additional configuration, mostly passed to fetch as its 'init' config
+ * @param  {Object}  config Additional configuration, mostly passed to fetch as its 'init' config
  *                          (see https://developer.mozilla.org/en-US/docs/Web/API/GlobalFetch/fetch#Parameters).
  * @param  {*}             config.jsonBody        Json payload to the request. Will automatically be
  *                                                JSON.stringify()-ed and override `config.body`.
- * @param  {string|object} config.query           Query parameter to append to the end of the url.
+ * @param  {string|Object} config.query           Query parameter to append to the end of the url.
  *                                                If specified as an object, keys will be
  *                                                decamelized into snake case first.
- * @param  {*[]|object}    config.urlTemplateSpec Format spec to use to expand the url (see sprintf).
+ * @param  {*[]|Object}    config.urlTemplateSpec Format spec to use to expand the url (see sprintf).
  * @param  {*}             config.*               All other options are passed through to fetch.
  *
  * @return {Promise}        Promise that will resolve with the response if its status was 2xx;
@@ -47,8 +46,8 @@ export default function baseRequest(url, {
             // Use vsprintf for the array call signature
             expandedUrl = vsprintf(url, urlTemplateSpec)
         } else if (urlTemplateSpec &&
-                   typeof urlTemplateSpec === 'object' &&
-                   Object.keys(urlTemplateSpec).length) {
+            typeof urlTemplateSpec === 'object' &&
+            Object.keys(urlTemplateSpec).length) {
             expandedUrl = formatText(url, urlTemplateSpec)
         } else if (process.env.NODE_ENV !== 'production') {
             // eslint-disable-next-line no-console

diff --git a/src/connection.js b/src/connection.js
@@ -1,9 +1,10 @@
 import request from './request'
 
-
 const HEADER_BLACKLIST = ['content-type']
 
-
+/**
+ * Base connection
+ */
 export default class Connection {
     constructor(path, headers = {}) {
         this.path = path
@@ -38,7 +39,6 @@ export default class Connection {
     }
 
     /**
-     * @public
      * @param blockHeight
      */
     getBlock(blockHeight) {
@@ -50,7 +50,6 @@ export default class Connection {
     }
 
     /**
-     * @public
      * @param transactionId
      */
     getTransaction(transactionId) {
@@ -62,7 +61,6 @@ export default class Connection {
     }
 
     /**
-     * @public
      * @param transactionId
      * @param status
      */
@@ -75,7 +73,6 @@ export default class Connection {
     }
 
     /**
-     * @public
      * @param publicKey
      * @param spent
      */
@@ -94,7 +91,6 @@ export default class Connection {
     }
 
     /**
-     * @public
      * @param assetId
      * @param operation
      */
@@ -108,7 +104,6 @@ export default class Connection {
     }
 
     /**
-     * @public
      * @param blockId
      */
     listVotes(blockId) {
@@ -120,7 +115,6 @@ export default class Connection {
     }
 
     /**
-     * @public
      * @param transaction
      */
     postTransaction(transaction) {
@@ -131,7 +125,6 @@ export default class Connection {
     }
 
     /**
-     * @public
      * @param transaction
      */
     postTransactionSync(transaction) {
@@ -142,19 +135,16 @@ export default class Connection {
     }
 
     /**
-     * @public
      * @param transaction
      */
     postTransactionCommit(transaction) {
         return this._req(this.getApiUrls('transactionsCommit'), {
-
             method: 'POST',
             jsonBody: transaction
         })
     }
 
     /**
-     * @public
      * @param search
      */
     searchAssets(search) {
@@ -166,7 +156,6 @@ export default class Connection {
     }
 
     /**
-     * @public
      * @param search
      */
     searchMetadata(search) {

diff --git a/src/format_text.js b/src/format_text.js
@@ -11,7 +11,7 @@ const Regex = {
 
 /**
  * imported from https://github.com/bigchaindb/js-utility-belt/
- *
+ * @private
  * Formats strings similarly to C's sprintf, with the addition of '${...}' formats.
  *
  * Makes a first pass replacing '${...}' formats before passing the expanded string and other
@@ -47,6 +47,7 @@ export default function formatText(s, ...argv) {
             let interpolationLeft = replacement
 
             /**
+             * @private
              * Interpolation algorithm inspired by sprintf-js.
              *
              * Goes through the replacement string getting the left-most key or index to interpolate
@@ -69,7 +70,7 @@ export default function formatText(s, ...argv) {
                 // Assigning in the conditionals here makes the code less bloated
                 /* eslint-disable no-cond-assign */
                 while ((interpolationLeft = interpolationLeft.substring(curMatch[0].length)) &&
-                       value != null) {
+                    value != null) {
                     if ((curMatch = Regex.KEY_ACCESS.exec(interpolationLeft))) {
                         value = value[curMatch[1]]
                     } else if ((curMatch = Regex.INDEX_ACCESS.exec(interpolationLeft))) {

diff --git a/src/request.js b/src/request.js
@@ -1,14 +1,14 @@
 import baseRequest from './baseRequest'
 import sanitize from './sanitize'
 
-
 const DEFAULT_REQUEST_CONFIG = {
     headers: {
         'Accept': 'application/json'
     }
 }
 
 /**
+ * @private
  * Small wrapper around js-utility-belt's request that provides url resolving,
  * default settings, and response handling.
  */