Documentation with jsdoc

This commit is contained in:
Kagami Hiiragi 2014-12-30 20:00:28 +03:00
parent a3475d9d6a
commit e7b72ba569
10 changed files with 71 additions and 27 deletions

View File

@ -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)

13
jsdoc.json Normal file
View File

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

View File

@ -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
* @static
* @return {Promise.<Address>} 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.<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
* @static
* @return {Promise.<Address>} Generated address object.
*/
Address.fromRandom = function(opts) {
opts = opts || {};

View File

@ -1,8 +1,8 @@
/**
* Browser Bitmessage crypto implementation.
* Documentation: <http://www.w3.org/TR/WebCryptoAPI/>
* Browsers support: <http://caniuse.com/#feat=cryptography>
* Blink implementation details: <https://sites.google.com/a/chromium.org/dev/blink/webcrypto>
* @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";

View File

@ -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);

View File

@ -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;

View File

@ -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");

View File

@ -1,6 +1,6 @@
/**
* Implement `var_int` encoding/decoding.
* Reference: <https://bitmessage.org/wiki/Protocol_specification#Variable_length_integer>
* 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;

View File

@ -1,6 +1,6 @@
/**
* Implement WIF encoding/decoding.
* Reference: <https://en.bitcoin.it/wiki/Wallet_import_format>
* 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.<Buffer,undefined>} A promise than contain private
* key when fulfilled
* @param {string} wif - Encoded key
* @return {Promise.<Buffer>} 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.<string,undefined>} A promise that contains the
* encoded key when fulfilled
* @return {Promise.<string>} Encoded private key.
*/
exports.encode = function(privateKey) {
var data = Buffer.concat([new Buffer([0x80]), privateKey]);

View File

@ -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",