Documentation with jsdoc

README.md

@@ -4,6 +4,8 @@ JavaScript Bitmessage library for both browserify and node. The goal of this pro
 
 Public library API is currently in alpha stage, breaking changes are very likely to happen.
 
+API documentation available [here](https://bitchan.github.io/bitmessage/docs/).
+
 ## References
 
 * [Project wiki](https://bitmessage.org/wiki/Main_Page)

jsdoc.json

@@ -0,0 +1,13 @@
+{
+  "source": {
+    "include": ["lib", "README.md"]
+  },
+  "plugins": ["plugins/markdown"],
+  "markdown": {
+    "parser": "gfm"
+  },
+  "opts": {
+    "recurse": true,
+    "destination": "docs"
+  }
+}

lib/address.js

@@ -1,5 +1,6 @@
 /**
  * Working with Bitmessage addresses.
+ * @see {@link https://bitmessage.org/wiki/Address}
  * @module bitmessage/address
  */
 
@@ -36,8 +37,7 @@ function Address(opts) {
 /**
  * Parse Bitmessage address into address object.
  * @param {String} str - Address string (with or without `BM-` prefix)
- * @return {Promise.<Address,Error>} Decoded address object
+ * @return {Promise.<Address>} Decoded address object.
- * @static
  */
 Address.decode = function(str) {
   str = str.trim();
@@ -110,7 +110,7 @@ function keys2ripe(signKey, encKey) {
 /**
  * Calculate the Ripe hash of the address.
  * @param {?Object} opts - Options
- * @return {Promise.<Buffer,Error>} Resulting Ripe hash
+ * @return {Promise.<Buffer>} Resulting Ripe hash.
  */
 Address.prototype.getRipe = function(opts) {
   var self = this;
@@ -179,7 +179,7 @@ function checkripelen(ripelen, version) {
 
 /**
  * Encode Bitmessage address object into address string.
- * @return {Promise.<string,Error>} Address string
+ * @return {Promise.<string>} Address string.
  */
 Address.prototype.encode = function() {
   var self = this;
@@ -200,8 +200,7 @@ Address.prototype.encode = function() {
  * Create new Bitmessage address from random encryption and signing
  * private keys.
  * @param {?Object} opts - Address options
- * @return {Promise.<Address,Error>} Generated address object
+ * @return {Promise.<Address>} Generated address object.
- * @static
  */
 Address.fromRandom = function(opts) {
   opts = opts || {};

lib/crypto-platform.browser.js

@@ -1,8 +1,8 @@
 /**
  * Browser Bitmessage crypto implementation.
- * Documentation: <http://www.w3.org/TR/WebCryptoAPI/>
+ * @see {@link http://www.w3.org/TR/WebCryptoAPI/}
- * Browsers support: <http://caniuse.com/#feat=cryptography>
+ * @see {@link http://caniuse.com/#feat=cryptography}
- * Blink implementation details: <https://sites.google.com/a/chromium.org/dev/blink/webcrypto>
+ * @see {@link https://sites.google.com/a/chromium.org/dev/blink/webcrypto}
  */
 
 "use strict";

lib/crypto-platform.js

@@ -8,18 +8,33 @@
 require("es6-promise").polyfill();
 var crypto = require("crypto");
 
+/**
+ * Calculate SHA-512 hash.
+ * @param {Buffer} buf - Input data
+ * @return {Promise.<Buffer>} Resulting hash.
+ */
 exports.sha512 = function(buf) {
   var hash = crypto.createHash("sha512");
   hash.update(buf);
   return Promise.resolve(hash.digest());
 };
 
+/**
+ * Calculate SHA-256 hash.
+ * @param {Buffer} buf - Input data
+ * @return {Promise.<Buffer>} Resulting hash.
+ */
 exports.sha256 = function(buf) {
   var hash = crypto.createHash("sha256");
   hash.update(buf);
   return Promise.resolve(hash.digest());
 };
 
+/**
+ * Calculate RIPEMD-160 hash.
+ * @param {Buffer} buf - Input data
+ * @return {Promise.<Buffer>} Resulting hash.
+ */
 exports.ripemd160 = function(buf) {
   var hash = crypto.createHash("ripemd160");
   hash.update(buf);

lib/crypto.js

@@ -1,6 +1,7 @@
 /**
- * Isomorphic Bitmessage crypto module. Reexports platform-specific
+ * Isomorphic Bitmessage crypto module. Reexports
- * functions and also some common routines.
+ * [platform-specific functions]{@link module:bitmessage/crypto-platform}
+ * and also some common routines.
  * @module bitmessage/crypto
  */
 
@@ -21,4 +22,10 @@ exports.getPrivate = function() {
   return cryptoPlatform.randomBytes(32);
 };
 
+/**
+ * Generate public key for a given private key.
+ * @param {Buffer} privateKey - Private key
+ * @return {Buffer} Public key.
+ * @function
+ */
 exports.getPublic = eccrypto.getPublic;

lib/index.js

@@ -5,8 +5,15 @@
 
 "use strict";
 
-// uint64_t implementation used for operations with int64. You may
+/**
-// replace it with other library with the same API.
+ * `uint64_t` implementation used to represent such numbers in
+ * JavaScript. Default is
+ * [int64-native](https://www.npmjs.com/package/int64-native) for Node
+ * platform and [node-int64](https://www.npmjs.com/package/node-int64)
+ * for Browser. You may replace it with other library with the same API.
+ */
 exports.Int64 = require("int64-native");
+/** Working with addresses. */
 exports.Address = require("./address");
+/** Working with WIF. */
 exports.wif = require("./wif");

lib/varint.js

@@ -1,6 +1,6 @@
 /**
- * Implement `var_int` encoding/decoding.
+ * Implements `var_int` encoding/decoding.
- * Reference: <https://bitmessage.org/wiki/Protocol_specification#Variable_length_integer>
+ * @see {@link https://bitmessage.org/wiki/Protocol_specification#Variable_length_integer}
  * @module bitmessage/varint
  */
 
@@ -12,7 +12,8 @@ var bitmessage = require("./");
 /**
  * Decode var_int.
  * @param {Buffer} buf - Buffer that starts with encoded var_int
- * @return {var_int} Decoded var_int structure
+ * @return {{value: (number|Int64), length: number, rest: number}}
+ * Decoded var_int structure.
  */
 exports.decode = function(buf) {
   assert(buf.length > 0, "Empty buffer");
@@ -46,7 +47,7 @@ exports.decode = function(buf) {
 /**
  * Encode number into var_int.
  * @param {(number|Int64|Buffer)} value - Input number
- * @return {Buffer} Encoded var_int
+ * @return {Buffer} Encoded var_int.
  */
 exports.encode = function(value) {
   var buf, buf64, targetStart;

lib/wif.js

@@ -1,6 +1,6 @@
 /**
- * Implement WIF encoding/decoding.
+ * Implements WIF encoding/decoding.
- * Reference: <https://en.bitcoin.it/wiki/Wallet_import_format>
+ * @see {@link https://en.bitcoin.it/wiki/Wallet_import_format}
  * @module bitmessage/wif
  */
 
@@ -21,14 +21,13 @@ function getchecksum(data) {
 
 /**
  * Decode WIF encoded private key.
- * @param {string} input - Input data
+ * @param {string} wif - Encoded key
- * @param {Promise.<Buffer,undefined>} A promise than contain private
+ * @return {Promise.<Buffer>} Private key.
- * key when fulfilled
  */
-exports.decode = function(input) {
+exports.decode = function(wif) {
   var bytes;
   try {
-    bytes = bs58.decode(input);
+    bytes = bs58.decode(wif);
     assert(bytes[0] === 0x80, "Bad WIF");
   } catch(e) {
     return Promise.reject(e);
@@ -44,8 +43,7 @@ exports.decode = function(input) {
 /**
  * Convert private key to a WIF.
  * @param {Buffer} privateKey - A private key to encode
- * @return {Promise.<string,undefined>} A promise that contains the
+ * @return {Promise.<string>} Encoded private key.
- * encoded key when fulfilled
  */
 exports.encode = function(privateKey) {
   var data = Buffer.concat([new Buffer([0x80]), privateKey]);

package.json

@@ -13,7 +13,8 @@
     "k": "xvfb-run -a karma start",
     "kc": "xvfb-run -a karma start --browsers Chromium",
     "kf": "xvfb-run -a karma start --browsers Firefox",
-    "j": "jshint ."
+    "j": "jshint .",
+    "docs": "jsdoc -c jsdoc.json"
   },
   "repository": {
     "type": "git",
@@ -33,6 +34,7 @@
   "homepage": "https://github.com/bitchan/bitmessage",
   "devDependencies": {
     "chai": "*",
+    "jsdoc": "^3.3.0-alpha13",
     "jshint": "*",
     "karma": "^0.12.28",
     "karma-browserify": "^1.0.1",