From e7b72ba569783ce77ab3dd912dae04c0a3a9f630 Mon Sep 17 00:00:00 2001 From: Kagami Hiiragi Date: Tue, 30 Dec 2014 20:00:28 +0300 Subject: [PATCH] Documentation with jsdoc --- README.md | 2 ++ jsdoc.json | 13 +++++++++++++ lib/address.js | 11 +++++------ lib/crypto-platform.browser.js | 6 +++--- lib/crypto-platform.js | 15 +++++++++++++++ lib/crypto.js | 11 +++++++++-- lib/index.js | 11 +++++++++-- lib/varint.js | 9 +++++---- lib/wif.js | 16 +++++++--------- package.json | 4 +++- 10 files changed, 71 insertions(+), 27 deletions(-) create mode 100644 jsdoc.json diff --git a/README.md b/README.md index cde1025..d34cc98 100644 --- a/README.md +++ b/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) diff --git a/jsdoc.json b/jsdoc.json new file mode 100644 index 0000000..7529d86 --- /dev/null +++ b/jsdoc.json @@ -0,0 +1,13 @@ +{ + "source": { + "include": ["lib", "README.md"] + }, + "plugins": ["plugins/markdown"], + "markdown": { + "parser": "gfm" + }, + "opts": { + "recurse": true, + "destination": "docs" + } +} diff --git a/lib/address.js b/lib/address.js index 178be7e..1bfcd0a 100644 --- a/lib/address.js +++ b/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.} Decoded address object - * @static + * @return {Promise.
} Decoded address object. */ 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.} Resulting Ripe hash + * @return {Promise.} 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.} Address string + * @return {Promise.} 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.} Generated address object - * @static + * @return {Promise.
} Generated address object. */ Address.fromRandom = function(opts) { opts = opts || {}; diff --git a/lib/crypto-platform.browser.js b/lib/crypto-platform.browser.js index aeec1ab..c8e521f 100644 --- a/lib/crypto-platform.browser.js +++ b/lib/crypto-platform.browser.js @@ -1,8 +1,8 @@ /** * Browser Bitmessage crypto implementation. - * Documentation: - * Browsers support: - * Blink implementation details: + * @see {@link http://www.w3.org/TR/WebCryptoAPI/} + * @see {@link http://caniuse.com/#feat=cryptography} + * @see {@link https://sites.google.com/a/chromium.org/dev/blink/webcrypto} */ "use strict"; diff --git a/lib/crypto-platform.js b/lib/crypto-platform.js index 81ae9c0..0cb0ad8 100644 --- a/lib/crypto-platform.js +++ b/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.} 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.} 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.} Resulting hash. + */ exports.ripemd160 = function(buf) { var hash = crypto.createHash("ripemd160"); hash.update(buf); diff --git a/lib/crypto.js b/lib/crypto.js index d5d7724..7588efa 100644 --- a/lib/crypto.js +++ b/lib/crypto.js @@ -1,6 +1,7 @@ /** - * Isomorphic Bitmessage crypto module. Reexports platform-specific - * functions and also some common routines. + * Isomorphic Bitmessage crypto module. Reexports + * [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; diff --git a/lib/index.js b/lib/index.js index 1045c2c..02ce5bf 100644 --- a/lib/index.js +++ b/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"); diff --git a/lib/varint.js b/lib/varint.js index 9af832c..755033f 100644 --- a/lib/varint.js +++ b/lib/varint.js @@ -1,6 +1,6 @@ /** - * Implement `var_int` encoding/decoding. - * Reference: + * Implements `var_int` encoding/decoding. + * @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; diff --git a/lib/wif.js b/lib/wif.js index 9c62451..17bd5cf 100644 --- a/lib/wif.js +++ b/lib/wif.js @@ -1,6 +1,6 @@ /** - * Implement WIF encoding/decoding. - * Reference: + * Implements WIF encoding/decoding. + * @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 {Promise.} A promise than contain private - * key when fulfilled + * @param {string} wif - Encoded key + * @return {Promise.} Private key. */ -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.} A promise that contains the - * encoded key when fulfilled + * @return {Promise.} Encoded private key. */ exports.encode = function(privateKey) { var data = Buffer.concat([new Buffer([0x80]), privateKey]); diff --git a/package.json b/package.json index c251c7c..d7e7f1e 100644 --- a/package.json +++ b/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",