From 6511d95cb69ff602c424869bdd892e0fd639501b Mon Sep 17 00:00:00 2001 From: juanelas Date: Wed, 8 Apr 2020 11:53:15 +0200 Subject: [PATCH] better documentation --- README.md | 105 ++++++++++-------- build/build.docs.js | 32 ++++-- build/rollup.config.js | 24 ++-- ...bundle.js => index.browser.bundle.iife.js} | 0 lib/index.browser.mod.js | 5 + lib/index.node.js | 5 + package.json | 4 +- src/doc/readme-template.md | 23 ++-- src/js/index.js | 5 + types/index.d.ts | 4 + 10 files changed, 126 insertions(+), 81 deletions(-) rename lib/{index.browser.bundle.js => index.browser.bundle.iife.js} (100%) diff --git a/README.md b/README.md index 2658eb2..4849533 100644 --- a/README.md +++ b/README.md @@ -17,7 +17,7 @@ npm install bigint-mod-arith ``` NPM installation defaults to the ES6 module for browsers and the CJS one for Node.js. -For web browsers, you can also directly download the [IIFE bundle](https://raw.githubusercontent.com/juanelas/bigint-mod-arith/master/lib/index.browser.bundle.js) or the [ES6 bundle module](https://raw.githubusercontent.com/juanelas/bigint-mod-arith/master/lib/index.browser.bundle.mod.js) from GitHub. +For web browsers, you can also directly download the [IIFE bundle](https://raw.githubusercontent.com/juanelas/bigint-mod-arith/master/lib/index.browser.bundle.iife.js) or the [ES6 bundle module](https://raw.githubusercontent.com/juanelas/bigint-mod-arith/master/lib/index.browser.bundle.mod.js) from GitHub. ## Usage example @@ -28,17 +28,18 @@ Import your module as : const bigintModArith = require('bigint-mod-arith') ... // your code here ``` - - JavaScript native project + - JavaScript native or TypeScript project ```javascript import * as bigintModArith from 'bigint-mod-arith' ... // your code here ``` + > BigInt is [ES-2020](https://tc39.es/ecma262/#sec-bigint-objects). In order to use it with TypeScript you should set `lib` (and probably also `target` and `module`) to `esnext` in `tsconfig.json`. - JavaScript native browser ES6 mod ```html + import * as bigintModArith from 'lib/index.browser.bundle.mod.js' // Use you actual path to the broser mod bundle + ... // your code here + ``` - JavaScript native browser IIFE ```html @@ -46,12 +47,9 @@ Import your module as : - - TypeScript - ```typescript - import * as bigintModArith from 'bigint-mod-arith' - ... // your code here ``` - > BigInt is [ES-2020](https://tc39.es/ecma262/#sec-bigint-objects). In order to use it with TypeScript you should set `lib` (and probably also `target` and `module`) to `esnext` in `tsconfig.json`. + +And you could use it like in the following: ```javascript /* Stage 3 BigInts with value 666 can be declared as BigInt('666') @@ -74,50 +72,69 @@ console.log(bigintModArith.modInv(BigInt('3'), BigInt('5'))) // prints 2 ## API reference documentation - + -### abs(a) ⇒ bigint +### bigint-mod-arith +Some common functions for modular arithmetic using native JS implementation of BigInt + + +* [bigint-mod-arith](#module_bigint-mod-arith) + * [~abs(a)](#module_bigint-mod-arith..abs) ⇒ bigint + * [~bitLength(a)](#module_bigint-mod-arith..bitLength) ⇒ number + * [~eGcd(a, b)](#module_bigint-mod-arith..eGcd) ⇒ egcdReturn + * [~gcd(a, b)](#module_bigint-mod-arith..gcd) ⇒ bigint + * [~lcm(a, b)](#module_bigint-mod-arith..lcm) ⇒ bigint + * [~max(a, b)](#module_bigint-mod-arith..max) ⇒ bigint + * [~min(a, b)](#module_bigint-mod-arith..min) ⇒ bigint + * [~modInv(a, n)](#module_bigint-mod-arith..modInv) ⇒ bigint + * [~modPow(b, e, n)](#module_bigint-mod-arith..modPow) ⇒ bigint + * [~toZn(a, n)](#module_bigint-mod-arith..toZn) ⇒ bigint + * [~egcdReturn](#module_bigint-mod-arith..egcdReturn) : Object + + + +#### bigint-mod-arith~abs(a) ⇒ bigint Absolute value. abs(a)==a if a>=0. abs(a)==-a if a<0 -**Kind**: global function +**Kind**: inner method of [bigint-mod-arith](#module_bigint-mod-arith) **Returns**: bigint - the absolute value of a | Param | Type | | --- | --- | | a | number \| bigint | - + -### bitLength(a) ⇒ number +#### bigint-mod-arith~bitLength(a) ⇒ number Returns the bitlength of a number -**Kind**: global function +**Kind**: inner method of [bigint-mod-arith](#module_bigint-mod-arith) **Returns**: number - - the bit length | Param | Type | | --- | --- | | a | number \| bigint | - + -### eGcd(a, b) ⇒ [egcdReturn](#egcdReturn) +#### bigint-mod-arith~eGcd(a, b) ⇒ egcdReturn An iterative implementation of the extended euclidean algorithm or extended greatest common divisor algorithm. Take positive integers a, b as input, and return a triple (g, x, y), such that ax + by = g = gcd(a, b). -**Kind**: global function -**Returns**: [egcdReturn](#egcdReturn) - A triple (g, x, y), such that ax + by = g = gcd(a, b). +**Kind**: inner method of [bigint-mod-arith](#module_bigint-mod-arith) +**Returns**: egcdReturn - A triple (g, x, y), such that ax + by = g = gcd(a, b). | Param | Type | | --- | --- | | a | number \| bigint | | b | number \| bigint | - + -### gcd(a, b) ⇒ bigint +#### bigint-mod-arith~gcd(a, b) ⇒ bigint Greatest-common divisor of two integers based on the iterative binary algorithm. -**Kind**: global function +**Kind**: inner method of [bigint-mod-arith](#module_bigint-mod-arith) **Returns**: bigint - The greatest common divisor of a and b | Param | Type | @@ -125,12 +142,12 @@ Greatest-common divisor of two integers based on the iterative binary algorithm. | a | number \| bigint | | b | number \| bigint | - + -### lcm(a, b) ⇒ bigint +#### bigint-mod-arith~lcm(a, b) ⇒ bigint The least common multiple computed as abs(a*b)/gcd(a,b) -**Kind**: global function +**Kind**: inner method of [bigint-mod-arith](#module_bigint-mod-arith) **Returns**: bigint - The least common multiple of a and b | Param | Type | @@ -138,12 +155,12 @@ The least common multiple computed as abs(a*b)/gcd(a,b) | a | number \| bigint | | b | number \| bigint | - + -### max(a, b) ⇒ bigint +#### bigint-mod-arith~max(a, b) ⇒ bigint Maximum. max(a,b)==a if a>=b. max(a,b)==b if a<=b -**Kind**: global function +**Kind**: inner method of [bigint-mod-arith](#module_bigint-mod-arith) **Returns**: bigint - maximum of numbers a and b | Param | Type | @@ -151,12 +168,12 @@ Maximum. max(a,b)==a if a>=b. max(a,b)==b if a<=b | a | number \| bigint | | b | number \| bigint | - + -### min(a, b) ⇒ bigint +#### bigint-mod-arith~min(a, b) ⇒ bigint Minimum. min(a,b)==b if a>=b. min(a,b)==a if a<=b -**Kind**: global function +**Kind**: inner method of [bigint-mod-arith](#module_bigint-mod-arith) **Returns**: bigint - minimum of numbers a and b | Param | Type | @@ -164,12 +181,12 @@ Minimum. min(a,b)==b if a>=b. min(a,b)==a if a<=b | a | number \| bigint | | b | number \| bigint | - + -### modInv(a, n) ⇒ bigint +#### bigint-mod-arith~modInv(a, n) ⇒ bigint Modular inverse. -**Kind**: global function +**Kind**: inner method of [bigint-mod-arith](#module_bigint-mod-arith) **Returns**: bigint - the inverse modulo n or NaN if it does not exist | Param | Type | Description | @@ -177,12 +194,12 @@ Modular inverse. | a | number \| bigint | The number to find an inverse for | | n | number \| bigint | The modulo | - + -### modPow(b, e, n) ⇒ bigint +#### bigint-mod-arith~modPow(b, e, n) ⇒ bigint Modular exponentiation b**e mod n. Currently using the right-to-left binary method -**Kind**: global function +**Kind**: inner method of [bigint-mod-arith](#module_bigint-mod-arith) **Returns**: bigint - b**e mod n | Param | Type | Description | @@ -191,12 +208,12 @@ Modular exponentiation b**e mod n. Currently using the right-to-left binary meth | e | number \| bigint | exponent | | n | number \| bigint | modulo | - + -### toZn(a, n) ⇒ bigint +#### bigint-mod-arith~toZn(a, n) ⇒ bigint Finds the smallest positive element that is congruent to a in modulo n -**Kind**: global function +**Kind**: inner method of [bigint-mod-arith](#module_bigint-mod-arith) **Returns**: bigint - The smallest positive representation of a in modulo n | Param | Type | Description | @@ -204,12 +221,12 @@ Finds the smallest positive element that is congruent to a in modulo n | a | number \| bigint | An integer | | n | number \| bigint | The modulo | - + -### egcdReturn : Object +#### bigint-mod-arith~egcdReturn : Object A triple (g, x, y), such that ax + by = g = gcd(a, b). -**Kind**: global typedef +**Kind**: inner typedef of [bigint-mod-arith](#module_bigint-mod-arith) **Properties** | Name | Type | diff --git a/build/build.docs.js b/build/build.docs.js index 4db18de..172cba7 100644 --- a/build/build.docs.js +++ b/build/build.docs.js @@ -7,18 +7,34 @@ const pkgJson = require('../package.json') const rootDir = path.join(__dirname, '..') -const template = path.join(rootDir, pkgJson.directories.src, 'doc', 'readme-template.md') -const input = path.join(rootDir, pkgJson.directories.lib, 'index.node.js') +function camelise (str) { + return str.replace(/-([a-z])/g, + function (m, w) { + return w.toUpperCase() + }) +} + +const templateFile = path.join(rootDir, pkgJson.directories.src, 'doc', 'readme-template.md') +const template = fs.readFileSync(templateFile, { encoding: 'UTF-8' }) + .replace(/\{\{PKG_NAME\}\}/g, pkgJson.name) + .replace(/\{\{PKG_CAMELCASE\}\}/g, camelise(pkgJson.name)) + .replace(/\{\{IIFE_BUNDLE\}\}/g, 'IIFE bundle') + .replace(/\{\{ESM_BUNDLE\}\}/g, 'ES6 bundle module') + +const input = path.join(rootDir, pkgJson.browser) +// Let us replace bigint literals by standard numbers to avoid issues with bigint +const source = fs.readFileSync(input, { encoding: 'UTF-8' }).replace(/([0-9]+)n([,\s\n)])/g, '$1$2') const options = { - source: fs.readFileSync(input, { encoding: 'UTF-8' }), // we need to use this instead of files in order to avoid issues with esnext features - template: fs.readFileSync(template, { encoding: 'UTF-8' }), + source, + template, 'heading-depth': 3, // The initial heading depth. For example, with a value of 2 the top-level markdown headings look like "## The heading" 'global-index-format': 'none' // none, grouped, table, dl. } -const readmeContents = jsdoc2md.renderSync(options) +jsdoc2md.clear().then(() => { + const readmeContents = jsdoc2md.renderSync(options) -const readmeFile = path.join(rootDir, 'README.md') - -fs.writeFileSync(readmeFile, readmeContents) + const readmeFile = path.join(rootDir, 'README.md') + fs.writeFileSync(readmeFile, readmeContents) +}) diff --git a/build/rollup.config.js b/build/rollup.config.js index 0b10820..8469153 100644 --- a/build/rollup.config.js +++ b/build/rollup.config.js @@ -12,7 +12,6 @@ const srcDir = path.join(rootDir, pkgJson.directories.src) const dstDir = path.join(rootDir, pkgJson.directories.lib) function camelise (str) { - console.log('camelise', str) return str.replace(/-([a-z])/g, function (m, w) { return w.toUpperCase() @@ -25,12 +24,12 @@ const pkgCamelisedName = camelise(pkgName) const input = path.join(srcDir, 'js', 'index.js') module.exports = [ - { // ESM native module + { // Native JS input: input, output: [ { - file: path.join(dstDir, 'index.browser.mod.js'), - format: 'esm' + file: path.join(rootDir, pkgJson.browser), + format: 'es' } ], plugins: [ @@ -44,7 +43,7 @@ module.exports = [ input: input, output: [ { - file: path.join(dstDir, 'index.browser.bundle.js'), + file: path.join(dstDir, 'index.browser.bundle.iife.js'), format: 'iife', name: pkgCamelisedName }, @@ -60,23 +59,20 @@ module.exports = [ resolve({ browser: true }), - terser({ - // mangle: false, - // compress: false - }) + terser() ] }, { // Node input: input, + output: { + file: path.join(rootDir, pkgJson.main), + format: 'cjs' + }, plugins: [ replace({ 'process.browser': false }) - ], - output: { - file: path.join(dstDir, 'index.node.js'), - format: 'cjs' - } + ] // external: ['bigint-crypto-utils'] } ] diff --git a/lib/index.browser.bundle.js b/lib/index.browser.bundle.iife.js similarity index 100% rename from lib/index.browser.bundle.js rename to lib/index.browser.bundle.iife.js diff --git a/lib/index.browser.mod.js b/lib/index.browser.mod.js index dccceb3..38b3772 100644 --- a/lib/index.browser.mod.js +++ b/lib/index.browser.mod.js @@ -1,3 +1,8 @@ +/** + * Some common functions for modular arithmetic using native JS implementation of BigInt + * @module bigint-mod-arith + */ + /** * Absolute value. abs(a)==a if a>=0. abs(a)==-a if a<0 * diff --git a/lib/index.node.js b/lib/index.node.js index f471282..c447d89 100644 --- a/lib/index.node.js +++ b/lib/index.node.js @@ -2,6 +2,11 @@ Object.defineProperty(exports, '__esModule', { value: true }) +/** + * Some common functions for modular arithmetic using native JS implementation of BigInt + * @module bigint-mod-arith + */ + /** * Absolute value. abs(a)==a if a>=0. abs(a)==-a if a<0 * diff --git a/package.json b/package.json index 831b417..14a668f 100644 --- a/package.json +++ b/package.json @@ -1,7 +1,7 @@ { "name": "bigint-mod-arith", "version": "2.0.4", - "description": "Some additional common functions for modular arithmetics using native JS (stage 3) implementation of BigInt", + "description": "Some common functions for modular arithmetic using native JS implementation of BigInt", "keywords": [ "modular arithmetics", "BigInt", @@ -49,7 +49,7 @@ ], "ignore": [ "/test/browser/", - "/lib/index.browser.bundle.js", + "/lib/index.browser.bundle.iife.js", "/lib/index.browser.bundle.mod.js" ] }, diff --git a/src/doc/readme-template.md b/src/doc/readme-template.md index 29a50cd..6d0f707 100644 --- a/src/doc/readme-template.md +++ b/src/doc/readme-template.md @@ -17,7 +17,7 @@ npm install bigint-mod-arith ``` NPM installation defaults to the ES6 module for browsers and the CJS one for Node.js. -For web browsers, you can also directly download the [IIFE bundle](https://raw.githubusercontent.com/juanelas/bigint-mod-arith/master/lib/index.browser.bundle.js) or the [ES6 bundle module](https://raw.githubusercontent.com/juanelas/bigint-mod-arith/master/lib/index.browser.bundle.mod.js) from GitHub. +For web browsers, you can also directly download the [IIFE bundle](https://raw.githubusercontent.com/juanelas/bigint-mod-arith/master/lib/index.browser.bundle.iife.js) or the [ES6 bundle module](https://raw.githubusercontent.com/juanelas/bigint-mod-arith/master/lib/index.browser.bundle.mod.js) from GitHub. ## Usage example @@ -25,20 +25,21 @@ Import your module as : - Node.js ```javascript - const bigintModArith = require('bigint-mod-arith') + const {{PKG_CAMELCASE}} = require('{{PKG_NAME}}') ... // your code here ``` - - JavaScript native project + - JavaScript native or TypeScript project ```javascript - import * as bigintModArith from 'bigint-mod-arith' + import * as {{PKG_CAMELCASE}} from '{{PKG_NAME}}' ... // your code here ``` + > BigInt is [ES-2020](https://tc39.es/ecma262/#sec-bigint-objects). In order to use it with TypeScript you should set `lib` (and probably also `target` and `module`) to `esnext` in `tsconfig.json`. - JavaScript native browser ES6 mod ```html + import * as {{PKG_CAMELCASE}} from 'lib/index.browser.bundle.mod.js' // Use you actual path to the broser mod bundle + ... // your code here + ``` - JavaScript native browser IIFE ```html @@ -47,12 +48,8 @@ Import your module as : ... // your code here ``` - - TypeScript - ```typescript - import * as bigintModArith from 'bigint-mod-arith' - ... // your code here - ``` - > BigInt is [ES-2020](https://tc39.es/ecma262/#sec-bigint-objects). In order to use it with TypeScript you should set `lib` (and probably also `target` and `module`) to `esnext` in `tsconfig.json`. + +And you could use it like in the following: ```javascript /* Stage 3 BigInts with value 666 can be declared as BigInt('666') diff --git a/src/js/index.js b/src/js/index.js index 947d0c8..9aeeb20 100644 --- a/src/js/index.js +++ b/src/js/index.js @@ -1,3 +1,8 @@ +/** + * Some common functions for modular arithmetic using native JS implementation of BigInt + * @module bigint-mod-arith + */ + /** * Absolute value. abs(a)==a if a>=0. abs(a)==-a if a<0 * diff --git a/types/index.d.ts b/types/index.d.ts index 669a535..5c0d6f0 100644 --- a/types/index.d.ts +++ b/types/index.d.ts @@ -6,6 +6,10 @@ export type egcdReturn = { x: bigint; y: bigint; }; +/** + * Some common functions for modular arithmetic using native JS implementation of BigInt + * @module bigint-mod-arith + */ /** * Absolute value. abs(a)==a if a>=0. abs(a)==-a if a<0 *