Improved documentation

[m1sta]

Have just started using node-sodium. Fantastic library but an absolute pain to get up and running with due to the combination of 'very-light' documentation and the dynamic nature of javascript.

Would http://www.verious.com/code/adamcaudill/libsodium-net/ be of any value in getting improved documentation up and running or perhaps this (generated by https://gist.github.com/m1sta/8229574)...

    api
        sodium_version_string()
        sodium_library_version_minor()
        sodium_library_version_major()
        memzero()
        memcmp()
        randombytes_buf()
        randombytes_close()
        randombytes_stir()
        randombytes_random()
        randombytes_uniform()
        crypto_verify_16()
        crypto_verify_32()
        crypto_hash()
        crypto_hash_sha512()
        crypto_hash_sha256()
        crypto_hash_BYTES
        crypto_hash_BLOCKBYTES
        crypto_hash_PRIMITIVE
        crypto_auth()
        crypto_auth_verify()
        crypto_auth_BYTES
        crypto_auth_KEYBYTES
        crypto_auth_PRIMITIVE
        crypto_onetimeauth()
        crypto_onetimeauth_verify()
        crypto_onetimeauth_BYTES
        crypto_onetimeauth_KEYBYTES
        crypto_onetimeauth_PRIMITIVE
        crypto_stream()
        crypto_stream_xor()
        crypto_stream_KEYBYTES
        crypto_stream_NONCEBYTES
        crypto_stream_PRIMITIVE
        crypto_secretbox()
        crypto_secretbox_open()
        crypto_secretbox_BOXZEROBYTES
        crypto_secretbox_KEYBYTES
        crypto_secretbox_NONCEBYTES
        crypto_secretbox_ZEROBYTES
        crypto_sign()
        crypto_sign_keypair()
        crypto_sign_open()
        crypto_sign_BYTES
        crypto_sign_PUBLICKEYBYTES
        crypto_sign_SECRETKEYBYTES
        crypto_box()
        crypto_box_keypair()
        crypto_box_open()
        crypto_box_beforenm()
        crypto_box_afternm()
        crypto_box_open_afternm()
        crypto_box_NONCEBYTES
        crypto_box_BEFORENMBYTES
        crypto_box_BOXZEROBYTES
        crypto_box_PUBLICKEYBYTES
        crypto_box_SECRETKEYBYTES
        crypto_box_ZEROBYTES
        crypto_box_PRIMITIVE
        crypto_shorthash()
        crypto_shorthash_BYTES
        crypto_shorthash_KEYBYTES
        crypto_shorthash_PRIMITIVE
        crypto_scalarmult()
        crypto_scalarmult_base()
        crypto_scalarmult_SCALARBYTES
        crypto_scalarmult_BYTES
        crypto_scalarmult_PRIMITIVE
    version
    versionMinor
    versionMajor
    Utils
        memzero()
        memcmp()
        verify16()
        verify32()
        toBuffer(value, encoding)
    Hash
        hash()
        sha256()
        sha512()
        bytes
        blockBytes
        primitive
    Random
        buffer()
        stir()
        close()
        rand()
        uniform()
    Box(publicKey, secretKey)
    Sign(key)
        verify(signature)
    Auth(secretKey, encoding)
    SecretBox(secretKey, encoding)
    Stream(secretKey, encoding)
    OneTimeAuth(secretKey, encoding)
    Nonces
        Box(nonce, encoding)
            super_()
        SecretBox(nonce, encoding)
            super_()
        Stream(nonce, encoding)
            super_()
    Key
        SecretBox(key, encoding)
            super_()
        Auth(key, encoding)
            super_()
        OneTimeAuth(key, encoding)
            super_()
        Stream(key, encoding)
            super_()
        Box(publicKey, secretKey, encoding)
            super_()
        Sign(publicKey, secretKey, encoding)
            super_()
        ECDH(publicKey, secretKey, encoding)
            super_()
    ECDH(publicKey, secretKey)
    Const
        ECDH
            scalarBytes
            bytes
            keyBytes
            primitive
        ScalarMult
            scalarBytes
            bytes
            primitive
        Hash
            bytes
            blockBytes
            primitive
        Box
            nonceBytes
            publicKeyBytes
            secretKeyBytes
            zeroBytes
            boxZeroBytes
            beforenmBytes
            primitive
        Auth
            bytes
            keyBytes
            primitive
        OneTimeAuth
            bytes
            keyBytes
            primitive
        SecretBox
            boxZeroBytes
            keyBytes
            nonceBytes
            zeroBytes
            primitive
        Sign
            bytes
            publicKeyBytes
            secretKeyBytes
            primitive
        Stream
            keyBytes
            nonceBytes
            primitive
        ShortHash
            bytes
            keyBytes
            primitive

[m1sta]

The utility functions in particular, could use some help. These might already exist elsewhere in the module but I found adding these useful...

sodium.api.crypto_box_random_nonce = function (){
    var nonce = new Buffer(sodium.crypto_box_NONCEBYTES);
    sodium.randombytes_buf(nonce);
    return nonce

}

sodium.api.to_hex = function (args) {
    var ret = "";
    for ( var i = 0; i < args.length; i++ )
        ret += (args[i] < 16 ? "0" : "") + args[i].toString(16);
    return ret; //.toUpperCase();
}

sodium.api.from_hex = function (str) {
    if (typeof str == 'string') {
        var ret = new Uint8Array(Math.floor(str.length / 2));
                var i = 0;
        str.replace(/(..)/g, function(str) { ret[i++] = parseInt(str, 16);});
        return ret;
    }
  }

[paixaop]

I will add the to_hex and from_hex. Random nonce is already generated by the nonce classes.

[paixaop]

Added to the Utils as 'api' is reserved to the core lib sodium functions