Docs: Reformat docs + tweaks

overlookmotel · Apr 30, 2023 · c0be9f9 · c0be9f9
1 parent ec87a8b
commit c0be9f9
Showing 1 changed file with 34 additions and 37 deletions.
diff --git a/README.md b/README.md
@@ -1,13 +1,9 @@
-# yauzl-promise.js
-
-# yauzl unzipping with Promises
-
-## Current status
-
 [![NPM version](https://img.shields.io/npm/v/yauzl-promise.svg)](https://www.npmjs.com/package/yauzl-promise)
 [![Build Status](https://img.shields.io/github/actions/workflow/status/overlookmotel/yauzl-promise/test.yml?branch=master)](https://github.com/overlookmotel/yauzl-promise/actions)
 [![Coverage Status](https://img.shields.io/coveralls/overlookmotel/yauzl-promise/master.svg)](https://coveralls.io/r/overlookmotel/yauzl-promise)
 
+# `yauzl` unzipping with Promises
+
 ## Usage
 
 Promisified version of [yauzl](https://www.npmjs.com/package/yauzl) for unzipping ZIP files.
@@ -25,9 +21,8 @@ npm install yauzl-promise
 These methods all work as before, but return a Promise rather than taking a callback.
 
 ```js
-const yauzl = require( 'yauzl-promise' );
-
-const zipFile = await yauzl.open( '/path/to/file' );
+const yauzl = require('yauzl-promise');
+const zipFile = await yauzl.open('/path/to/file.zip');
 ```
 
 `lazyEntries` option is automatically enabled. Get file entries using methods listed below.
@@ -41,7 +36,7 @@ Closes file and returns Promise which resolves when all streams are closed.
 Files **must** be closed when finished with to avoid resource leakages.
 
 ```js
-const zipFile = await yauzl.open( '/path/to/file' );
+const zipFile = await yauzl.open('/path/to/file.zip');
 await zipFile.close();
 ```
 
@@ -51,7 +46,7 @@ Same as original yauzl method, but returning a promise. Promise resolves to an i
 
 ```js
 const entry = await zipFile.readEntry();
-console.log( entry );
+console.log(entry);
 ```
 
 Calling `.readEntry()` again returns the next entry. When there are no entries left, it returns `null`.
@@ -61,8 +56,8 @@ Calling `.readEntry()` again returns the next entry. When there are no entries l
 Read several entries and return as an array.
 
 ```js
-const entries = await zipFile.readEntries( 3 );
-entries.forEach( console.log );
+const entries = await zipFile.readEntries(3);
+entries.forEach(console.log);
 ```
 
 If `numEntries` is `0`, `null` or `undefined`, reading will continue until all entries are read.
@@ -78,10 +73,10 @@ If `callback` returns a promise, the promise is awaited before reading the next
 Returns a promise which resolves when all have been read.
 
 ```js
-await zipFile.walkEntries( entry => {
-	console.log( entry );
-} );
-console.log( 'Done' );
+await zipFile.walkEntries(entry => {
+  console.log(entry);
+});
+console.log('Done');
 ```
 
 If `numEntries` is `0`, `null` or `undefined`, reading will continue until all entries are read.
@@ -91,8 +86,8 @@ If `numEntries` is `0`, `null` or `undefined`, reading will continue until all e
 Same as original method but returns promise of a stream.
 
 ```js
-const readStream = await zipFile.openReadStream( entry );
-readStream.pipe( writeStream );
+const readStream = await zipFile.openReadStream(entry);
+readStream.pipe(writeStream);
 ```
 
 #### `entry.openReadStream( [options] )`
@@ -102,7 +97,7 @@ As above, but called on an `Entry` object.
 ```js
 const entry = await zipFile.readEntry();
 const readStream = await entry.openReadStream();
-readStream.pipe( writeStream );
+readStream.pipe(writeStream);
 ```
 
 ### Events
@@ -122,44 +117,46 @@ Promises returned by default are native JS Promises.
 `.usePromise()` returns a new `yauzl` object where the methods return promises from the specified Promise constructor.
 
 ```js
-const Bluebird = require( 'bluebird' );
-const yauzl = require( 'yauzl-promise' ).usePromise( Bluebird );
+const Bluebird = require('bluebird');
+const yauzl = require('yauzl-promise').usePromise(Bluebird);
 
-const p = yauzl.open( '/path/to/file' );
-console.log( p instanceof Bluebird ); // true
+const p = yauzl.open('/path/to/file.zip');
+assert(p instanceof Bluebird);
 ```
 
 NB This does not alter the original `yauzl` object, only the one returned from `.usePromise()`.
 
 ```js
-const Bluebird = require( 'bluebird' );
-const yauzl = require( 'yauzl-promise' )
-const yauzlBluebird = yauzl.usePromise( Bluebird );
+const Bluebird = require('bluebird');
+const yauzl = require('yauzl-promise');
+const yauzlBluebird = yauzl.usePromise(Bluebird);
 
-const p = yauzl.open( '/path/to/file' );
-console.log( p instanceof Bluebird ); // false
+const p = yauzl.open('/path/to/file.zip');
+assert(p instanceof Promise);
+assert(!(p instanceof Bluebird));
 
-const p = yauzlBluebird.open( '/path/to/file' );
-console.log( p instanceof Bluebird ); // true
+const p = yauzlBluebird.open('/path/to/file.zip');
+assert(p instanceof Bluebird);
+assert(!(p instanceof Promise));
 ```
 
-#### Using another version of yauzl
+#### Using another version of `yauzl`
 
 `.useYauzl()` method promisifies a specific `yauzl` object.
 
 Only useful if you have a modified version of yauzl which you want to promisify.
 
 ```js
-const yauzlCrc = require( 'yauzl-crc' );
-const yauzl = require( 'yauzl-promise' ).useYauzl( yauzlCrc );
+const yauzlCrc = require('yauzl-crc');
+const yauzl = require('yauzl-promise').useYauzl(yauzlCrc);
 ```
 
 The yauzl object passed is cloned before it is modified, unless you set `clone` option to `false`:
 
 ```js
 const yauzlFork = require('my-yauzl-fork');
-const yauzl = require( 'yauzl-promise' ).useYauzl( yauzlFork, { clone: false } );
-console.log( yauzl == yauzlFork ); // true
+const yauzl = require('yauzl-promise').useYauzl(yauzlFork, { clone: false });
+assert(yauzl === yauzlFork);
 ```
 
 ## Versioning
@@ -185,6 +182,6 @@ If you discover a bug, please raise an issue on Github. https://github.com/overl
 Pull requests are very welcome. Please:
 
 * ensure all tests pass before submitting PR
-* add an entry to changelog
 * add tests for new features
 * document new functionality/API additions in README
+* do not add an entry to Changelog (Changelog is created when cutting releases)