add README.mkd, examples/examples.json, and minor comment cleanups

4 files changed, 173 insertions, 2 deletions

diff --git a/README.mkd b/README.mkd
new file mode 100644
index 0000000..19ee691
--- /dev/null
+++ b/README.mkd
@@ -0,0 +1,125 @@
+ZipStream-PHP 0.3.0
+===================
+
+Overview
+--------
+ZipStream-PHP is a library that allows you to dynamically generate
+streamed zip archives.
+
+Here's an example:
+
+    # import zipstream class
+    use Pablotron\ZipStream\ZipStream;
+    
+    # create the output stream
+    $zip = new ZipStream('example.zip');
+    
+    # add a file named "hello.txt" to output archive, containing the
+    # string "hello world!"
+    $zip->add_file('hello.txt', 'hello world!');
+    
+    # add a local file named "some-image.png" to the output archive as
+    # "picture.png"
+    $zip->add_file_from_path('picture.png', 'some-image.png');
+    
+    # finalize the output stream
+    $zip->close();
+
+Features:
+
+* Generate streamed archives without saving them to disk.
+* Files can be read from files, strings, streaming resources,
+  or generated dynamically.
+* Zip64 support: files and archives up to <code>2<sup>64</sup></code>
+  bytes in size
+* Stream output as an HTTP response, to a file on disk, to a resource
+  stream, or to a custom target.
+* [MIT][mit]-licensed: Use freely, even in commercial projects --
+  without restrictions.
+* Self-contained: Single source file with no required external
+  dependencies, so you can easily embed `ZipStream.php` directly into
+  your source tree if necessary.
+
+Dependencies
+------------
+
+* PHP: 7.0 or newer (required).
+* [Composer][composer]: Used for installation (optional, see below).
+* [phpDocumentor][phpdoc]: Used to generate the API documentation (optional).
+* [PHPUnit][phpunit]: Used to run the test suite (optional).
+
+*Note:* Consider an older version of ZipStream if you need PHP 5.x
+support.
+
+Installation
+------------
+### Using [Composer][composer]
+
+    # in your project root
+    composer require pablotron/zipstream
+
+Or add it to your top-level `composer.json`, like so:
+
+    "require": {
+      "pablotron/zipstream": "~0.3"
+    },
+
+### Manual Installation
+The source file for ZipStream is entirely self-contained, which means
+you can embed it directly in your project without using
+[Composer][composer] by doing the following:
+
+    # copy file to your project
+    cp src/ZipStream.php path/to/your/project/
+    
+    # then, somewhere in your project...
+    require_once 'path/to/ZipStream.php';
+
+Documentation
+-------------
+The API documentation is available online at the following URL:
+
+https://pablotron.github.io/zipstream-php/
+
+You can generate the API documentation using [Composer][composer], like
+so:
+
+    # generate api documentation in "docs/" directory
+    composer docs
+
+Brief usage examples are available in the `examples/` directory.
+
+Tests
+-----
+You can run the test suite via [Composer][composer] like so:
+
+    # run the test suite
+    composer test
+
+License
+-------
+Copyright 2007-2018 Paul Duncan <pabs@pablotron.org>
+
+Permission is hereby granted, free of charge, to any person obtaining a
+copy of this software and associated documentation files (the
+"Software"), to deal in the Software without restriction, including
+without limitation the rights to use, copy, modify, merge, publish,
+distribute, sublicense, and/or sell copies of the Software, and to
+permit persons to whom the Software is furnished to do so, subject to
+the following conditions:
+
+The above copyright notice and this permission notice shall be included
+in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS
+OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
+IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY
+CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT,
+TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE
+SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
+
+[composer]: https://getcomposer.org/
+[mit]: https://opensource.org/licenses/MIT
+[phpunit]: https://phpunit.de/
+[phpdoc]: https://phpdoc.org/
diff --git a/examples/examples.json b/examples/examples.json
new file mode 100644
index 0000000..f754a07
--- /dev/null
+++ b/examples/examples.json
@@ -0,0 +1,43 @@
+{
+  "examples": [{
+    "file": "01-simple.php",
+    "text": "Basic usage example."
+  }, {
+    "file": "02-add_file_from_path.php",
+    "text": "Add a file from a path."
+  }, {
+    "file": "03-add_stream.php",
+    "text": "Add file from a resource stream."
+  }, {
+    "file": "04-add.php",
+    "text": "Add a dynamically-generated file."
+  }, {
+    "file": "05-send.php",
+    "text": "Use `ZipStream::send`."
+  }, {
+    "file": "06-file_writer.php",
+    "text": "Write output to a file."
+  }, {
+    "file": "07-stream_writer.php",
+    "text": "Write output to a resource stream."
+  }, {
+    "file": "08-datetime.php",
+    "text": "Use a `DateTime` instance directly."
+  }, {
+    "file": "09-version.php",
+    "text": "Get the version of ZipStream."
+  }, {
+    "file": "10-archive_comment.php",
+    "text": "Add an archive comment."
+  }, {
+    "file": "11-add_file_comment.php",
+    "text": "Add a file comment."
+  }, {
+    "file": "12-add_file_methods.php",
+    "text": "Add a file with a specific compression method."
+  }, {
+    "file": "13-add_file_times.php",
+    "text": "Add a file with a specific modification time."
+  }]
+}
+
diff --git a/src/ZipStream.php b/src/ZipStream.php
index 437ff1d..8648b9f 100644
--- a/src/ZipStream.php
+++ b/src/ZipStream.php
@@ -14,6 +14,8 @@ namespace Pablotron\ZipStream;
 
 /**
  * Current version of ZipStream.
+ *
+ * @api
  */
 const VERSION = '0.3.0';
 
diff --git a/tests/LargeFileTest.php b/tests/LargeFileTest.php
index c271b47..b1106ec 100644
--- a/tests/LargeFileTest.php
+++ b/tests/LargeFileTest.php
@@ -8,11 +8,12 @@ use \Pablotron\ZipStream\ZipStream;
 
 final class LargeFileTest extends BaseTestCase {
   public function testCreateLargeFile() : void {
-    # build 4M string
+    # size and number of chunks
     $chunk_size = (1 << 22);
     $num_chunks = 1025;
 
-    # calculate expected size
+    # calculate expected file size (4299161600, enough to overflow a
+    # 32-bit integer and trigger zip64 mode)
     $expected_size = $chunk_size * $num_chunks;
 
     $this->with_temp_zip(function(ZipStream &$zip) use ($chunk_size, $num_chunks) {