From 52a5c6aa8f96761c7801f8e28d0541918cdffc23 Mon Sep 17 00:00:00 2001 From: Vitaly Puzrin Date: Thu, 20 Feb 2014 01:38:10 +0400 Subject: [PATCH] Added generated API docs --- .ndocrc | 4 +- Makefile | 2 +- README.md | 29 +++++--------- lib/deflate.js | 100 +++++++++++++++++++++++++++++++----------------- test/helpers.js | 1 + 5 files changed, 78 insertions(+), 58 deletions(-) diff --git a/.ndocrc b/.ndocrc index 996780f..5fa0a66 100644 --- a/.ndocrc +++ b/.ndocrc @@ -14,4 +14,6 @@ # Paths with sources ################################################################################ -lib +lib/deflate.js +lib/inflate.js +index.js diff --git a/Makefile b/Makefile index 33021fb..3a92167 100644 --- a/Makefile +++ b/Makefile @@ -91,5 +91,5 @@ publish: npm publish https://github.com/${GITHUB_PROJ}/tarball/${NPM_VERSION} -.PHONY: publish lint +.PHONY: publish lint doc .SILENT: help lint diff --git a/README.md b/README.md index 8a979d6..d1edba3 100644 --- a/README.md +++ b/README.md @@ -50,21 +50,19 @@ bower install pako Example & API ------------- +[Full docs](http://nodeca.github.io/pako/). + ```javascript var pako = require('pako'); -// // Deflate // - var input = new Uint8Array(); //... fill input data here var output = pako.deflate(input); -// // Inflate // - var compressed = new Uint8Array(); //... fill data to uncompress here var result = pako.inflate(compressed); @@ -75,24 +73,15 @@ var uncompressed = result.data; ``` -See docs for full API specs. - Notes ----- -Since pako was done mostly for browser, some specific functions were left unported. +Pako does not contains some very specific zlib functions. -deflate: - -- writing custom gzip headers (default is ok) -- `deflateSetDictionary`, `deflateParams`, `deflateSetHeader`, `deflateBound`, `deflatePending` - -inflate: - -TBD - -We will probably provide more modular design, to keep significant part of code reasonably small. +- __deflate__ - writing bustom gzip headers and methods `deflateSetDictionary`, + `deflateParams`, `deflateSetHeader`, `deflateBound`, `deflatePending`. +- __inflate__ - TBD. Authors @@ -101,9 +90,9 @@ Authors - Andrey Tupitsin [@anrd83](https://github.com/andr83) - Vitaly Puzrin [@puzrin](https://github.com/puzrin) -Personal thanks to Vyacheslav Egorov ([@mraleph](https://github.com/mraleph)) for -his awesome tutoruals about optimising JS code for v8, [IRHydra](http://mrale.ph/irhydra/) -tool and his advices. +Personal thanks to Vyacheslav Egorov ([@mraleph](https://github.com/mraleph)) +for his awesome tutoruals about optimising JS code for v8, +[IRHydra](http://mrale.ph/irhydra/) tool and his advices. License diff --git a/lib/deflate.js b/lib/deflate.js index 2e29d62..6befbbf 100644 --- a/lib/deflate.js +++ b/lib/deflate.js @@ -15,26 +15,57 @@ function sliceBuf(buf, size) { } /** - * new Deflate(ootions) + * class Deflate * + * Generic JS-style wrapper for zlib calls. If you don't need + * streaming behaviour - use more simple functions: [[deflate]], + * [[deflateRaw]] and [[gzip]]. + **/ + +/* internal + * Deflate.chunks -> Array + * + * Chunks of output data, if [[Deflate#onData]] not overriden. + **/ + +/** + * Deflate.result -> Uint8Array|Array + * + * Compressed result, generated by default [[Deflate#onData]] + * and [[Deflate#onEnd]] handlers. Filled after you push last chunk + * (call [[Deflate#push]] with `Z_FINISH` / `true` param). + **/ + +/** + * Deflate.err -> Number + * + * Error code after deflate finished. 0 (Z_OK) on success. + * You will not need it in real life, because deflate errors + * are possible only on wrong options or bad `onData` / `onEnd` + * custom handlers. + **/ + + +/** + * new Deflate(options) * - options (Object): zlib deflate options. * * Creates new deflator instance with specified params. Supported options: * - * - level - * - windowBits - * - memLevel - * - strategy + * - `level` + * - `windowBits` + * - `memLevel` + * - `strategy` * * [http://zlib.net/manual.html#Advanced](http://zlib.net/manual.html#Advanced) * for more information on these. * * Additional options, for internal needs: * - * - chunkSize - * - raw (boolean) - do raw deflate - * - gzip (boolean) - create gzip wrapper - */ + * - `chunkSize` - size of generated data chunks (16K by default) + * - `raw` (boolean) - do raw deflate + * - `gzip` (boolean) - create gzip wrapper + **/ var Deflate = function(options) { this.options = utils.assign({ @@ -77,16 +108,16 @@ var Deflate = function(options) { /** * Deflate#push(data[, mode]) -> Boolean - * - * - data (Uint8Array|Array) input data - * - mode (Number|Boolean) - 0..6 for corresponding Z_NO_FLUSH..Z_TREE modes. + * - data (Uint8Array|Array): input data + * - mode (Number|Boolean): 0..6 for corresponding Z_NO_FLUSH..Z_TREE modes. * See constants. Skipped or `false` means Z_NO_FLUSH, `true` meansh Z_FINISH. * - * Pipe input data, generating [Deflate.onData] calls with new compressed - * chunks. Returns `true` on success. The last chunk must have mode Z_FINISH. - * That flush pending data & call [Deflate.onEnd]. + * Sends input data to deflate pipe, generating [[Deflate#onData]] calls with + * new compressed chunks. Returns `true` on success. The last data block must have + * mode Z_FINISH (or `true`). That flush internal pending buffers and call + * [[Deflate#onEnd]]. * - * On fail call [Deflate.onEnd] with error code and return false. + * On fail call [[Deflate#onEnd]] with error code and return false. **/ Deflate.prototype.push = function(data, mode) { var strm = this.strm; @@ -135,12 +166,11 @@ Deflate.prototype.push = function(data, mode) { /** * Deflate#onData(chunk) -> Void - * - * - chunk (Uint8Array|Array)- ouput data. Type of array depends + * - chunk (Uint8Array|Array): ouput data. Type of array depends * on js engine support. * - * By default, it store chunks in [Deflate.chunks]. Override this handler, if - * you need another behaviour. + * By default, stores data blocks in `chunks[]` property and glue + * those in `onEnd`. Override this handler, if you need another behaviour. **/ Deflate.prototype.onData = function(chunk) { this.chunks.push(chunk); @@ -149,13 +179,12 @@ Deflate.prototype.onData = function(chunk) { /** * Deflate#onEnd(status) -> Void - * - * - status (Number) - deflate status. 0 (Z_OK) on success, + * - status (Number): deflate status. 0 (Z_OK) on success, * other if not. * - * Called once after you tell deflate that input stream complete. See - * [Deflate.finish]. By default - join collected chunks, free memory and fill - * states properties. + * Called once after you tell deflate that input stream complete. + * By default - join collected chunks, free memory and fill + * `results` / `err` properties. **/ Deflate.prototype.onEnd = function(status) { // On success - join @@ -171,14 +200,13 @@ Deflate.prototype.onEnd = function(status) { /** - * deflate(data, options) -> (Uint8Array|Array) - * + * deflate(data[, options]) -> Uint8Array|Array * - data (Uint8Array|Array): input data to compress. * - options (Object): zlib deflate options. * - * Simple [Deflate] wrapper to compress data with one call. + * Compress `data` with deflate alrorythm and `options`. * - * Supported options: + * Supported options are: * * - level * - windowBits @@ -186,7 +214,7 @@ Deflate.prototype.onEnd = function(status) { * - strategy * * [http://zlib.net/manual.html#Advanced](http://zlib.net/manual.html#Advanced) - * for more information on these. + * for more information on these. **/ function deflate(input, options) { var deflator = new Deflate(options); @@ -201,12 +229,12 @@ function deflate(input, options) { /** - * deflateRaw(data, options) -> (Uint8Array|Array) - * + * deflateRaw(data[, options]) -> Uint8Array|Array * - data (Uint8Array|Array): input data to compress. * - options (Object): zlib deflate options. * - * The same as [deflate], but auoput raw data, without wrapper. + * The same as [[deflate]], but creates raw data, without wrapper + * (header and adler32 crc). **/ function deflateRaw(input, options) { options = options || {}; @@ -216,12 +244,12 @@ function deflateRaw(input, options) { /** - * gzip(data, options) -> (Uint8Array|Array) - * + * gzip(data[, options]) -> Uint8Array|Array * - data (Uint8Array|Array): input data to compress. * - options (Object): zlib deflate options. * - * The same as [deflate], but create gzip wrapper instead of deflate one. + * The same as [[deflate]], but create gzip wrapper instead of + * deflate one. **/ function gzip(input, options) { options = options || {}; diff --git a/test/helpers.js b/test/helpers.js index 718b249..93d982d 100644 --- a/test/helpers.js +++ b/test/helpers.js @@ -37,6 +37,7 @@ function cmpBuf(a, b) { for (var i=0, l=a.length; i