Added generated API docs

.ndocrc

@@ -14,4 +14,6 @@
 # Paths with sources
 ################################################################################
 
-lib
+lib/deflate.js
+lib/inflate.js
+index.js

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

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:
+- __deflate__ - writing bustom gzip headers and methods `deflateSetDictionary`,
-
+  `deflateParams`, `deflateSetHeader`, `deflateBound`, `deflatePending`.
-- writing custom gzip headers (default is ok)
+- __inflate__ - TBD.
-- `deflateSetDictionary`, `deflateParams`, `deflateSetHeader`, `deflateBound`, `deflatePending`
-
-inflate:
-
-TBD
-
-We will probably provide more modular design, to keep significant part of code reasonably small.
 
 
 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
+Personal thanks to Vyacheslav Egorov ([@mraleph](https://github.com/mraleph))
-his awesome tutoruals about optimising JS code for v8, [IRHydra](http://mrale.ph/irhydra/)
+for his awesome tutoruals about optimising JS code for v8,
-tool and his advices.
+[IRHydra](http://mrale.ph/irhydra/) tool and his advices.
 
 
 License

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
+ * - `level`
- * - windowBits
+ * - `windowBits`
- * - memLevel
+ * - `memLevel`
- * - strategy
+ * - `strategy`
  *
  * [http://zlib.net/manual.html#Advanced](http://zlib.net/manual.html#Advanced)
  * for more information on these.
  *
  * Additional options, for internal needs:
  *
- * - chunkSize
+ * - `chunkSize` - size of generated data chunks (16K by default)
- * - raw (boolean) - do raw deflate
+ * - `raw` (boolean) - do raw deflate
- * - gzip (boolean) - create gzip wrapper
+ * - `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
- * - data (Uint8Array|Array) input data
+ * - mode (Number|Boolean): 0..6 for corresponding Z_NO_FLUSH..Z_TREE modes.
- * - 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
+ * Sends input data to deflate pipe, generating [[Deflate#onData]] calls with
- * chunks. Returns `true` on success. The last chunk must have mode Z_FINISH.
+ * new compressed chunks. Returns `true` on success. The last data block must have
- * That flush pending data & call [Deflate.onEnd].
+ * 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
+ * By default, stores data blocks in `chunks[]` property and glue
- *  you need another behaviour.
+ * 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
+ * Called once after you tell deflate that input stream complete.
- * [Deflate.finish]. By default - join collected chunks, free memory and fill
+ * By default - join collected chunks, free memory and fill
- * states properties.
+ * `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 || {};

test/helpers.js

@@ -37,6 +37,7 @@ function cmpBuf(a, b) {
 
   for (var i=0, l=a.length; i<l; i++) {
     if (a[i] !== b[i]) {
+      //console.log('pos: ' +i+ ' - ' + a[i].toString(16) + '/' + b[i].toString(16));
       return false;
     }
   }