Add rudimentary documentation.

Author: sebastianbergmann

README.markdown

@@ -27,3 +27,61 @@ This has to be done only once. Now the PEAR Installer can be used to install pac
     install ok: channel://pear.phpunit.de/PHP_CodeCoverage-0.9.0
 
 After the installation you can find the PHP_CodeCoverage source files inside your local PEAR directory; the path is usually `/usr/lib/php/PHP/CodeCoverage`.
+
+Using the PHP_CodeCoverage API
+------------------------------
+
+    <?php
+    require_once 'PHP/CodeCoverage.php';
+    require_once 'PHP/CodeCoverage/Report/Clover.php';
+    require_once 'PHP/CodeCoverage/Report/HTML.php';
+
+    $coverage = new PHP_CodeCoverage;
+    $coverage->start('<name of test>');
+
+    // ...
+
+    $coverage->stop();
+
+    $writer = new PHP_CodeCoverage_Report_Clover;
+    $writer->process($coverage, '/tmp/clover.xml');
+
+    $writer = new PHP_CodeCoverage_Report_HTML;
+    $writer->process($coverage, '/tmp/code-coverage-report');
+
+Using the `phpcov` tool
+-----------------------
+
+    sb@vmware examples % cat add.php
+    <?php
+    $a = 1;
+    $b = 2;
+    print $a + $b;
+
+    sb@vmware examples % phpcov --clover clover.xml add.php
+    phpcov 0.9.0 by Sebastian Bergmann.
+
+    3
+
+    sb@vmware examples % cat clover.xml
+    <?xml version="1.0" encoding="UTF-8"?>
+    <coverage generated="1270365900">
+      <project timestamp="1270365900">
+        <file name="/usr/local/src/bytekit-cli/examples/add.php">
+          <line num="2" type="stmt" count="1"/>
+          <line num="3" type="stmt" count="1"/>
+          <line num="4" type="stmt" count="1"/>
+          <line num="5" type="stmt" count="1"/>
+          <metrics loc="4" ncloc="4" classes="0" methods="0"
+                   coveredmethods="0" conditionals="0"
+                   coveredconditionals="0" statements="4"
+                   coveredstatements="4" elements="4"
+                   coveredelements="4"/>
+        </file>
+        <metrics files="1" loc="4" ncloc="4" classes="0" methods="0"
+                 coveredmethods="0" conditionals="0"
+                 coveredconditionals="0" statements="4"
+                 coveredstatements="4" elements="4"
+                 coveredelements="4"/>
+      </project>
+    </coverage>