Update README and generated code docs (#71)

* Simplifying and updating the README

* Fixing code blocks

* Update sami config to skip documentation for methods marked internal

* Fix documentation code blocks in integration code

* Fix links in docblocks

* Sami doesn't support 'see' annotations. Replace with links

* Add class examples for the samplers

* Fix phpcs

* Add badge images for latest released packagist version, add current status

* Need to indent code blocks in the ordered list

Author: chingor13

README.md

@@ -1,134 +1,67 @@
-# OpenCensus - A stats collection and distributed tracing framework
+# OpenCensus for PHP - A stats collection and distributed tracing framework
 
-This is the open-source release of Census for PHP. Census provides a
-framework to measure a server's resource usage and collect performance stats.
-This repository contains PHP related utilities and supporting software needed by
-Census.
+> [Census][census-org] for PHP. Census provides a framework to measure a
+server's resource usage and collect performance stats. This repository contains
+PHP related utilities and supporting software needed by Census.
 
-## Installation
+[![CircleCI](https://circleci.com/gh/census-instrumentation/opencensus-php.svg?style=svg)](https://circleci.com/gh/census-instrumentation/opencensus-php)
+[![Packagist](https://img.shields.io/packagist/v/opencensus/opencensus.svg)](https://packagist.org/packages/opencensus/opencensus)
+![PHP-Version](https://img.shields.io/packagist/php-v/opencensus/opencensus.svg)
 
-### PHP library
+* [API Documentation][api-docs]
 
-1. Install with `composer` or add to your `composer.json`.
+## Installation & basic usage
 
-```
-$ composer require opencensus/opencensus
-```
-
-2. Include and start the library as the first action in your application:
-
-```php
-use OpenCensus\Trace\RequestTracer;
-use OpenCensus\Trace\Exporter\EchoExporter;
-
-RequestTracer::start(new EchoExporter());
-```
+1. Install the `opencensus/opencensus` package using [composer][composer]:
 
-### PHP Extension
+    ```bash
+    $ composer require opencensus/opencensus
+    ```
 
-1. Install the `opencensus` extension from PECL.
+1. [Optional]: Install the `opencensus` extension from [PECL][pecl]:
 
-```
-$ pecl install opencensus
-```
+    ```bash
+    $ pecl install opencensus-devel
+    ```
+   Enable the extension in your `php.ini`:
 
-2. Enable the extension in your `php.ini`.
+    ```ini
+    extension=opencensus.so
+    ```
 
-```
-extension=opencensus.so
-```
+1. Initialize a tracer for your application:
 
-## Customizing
+    ```php
+    use OpenCensus\Trace\Tracer;
+    use OpenCensus\Trace\Exporter\EchoExporter;
 
-### Reporting Traces
+    Tracer::start(new EchoExporter());
+    ```
 
-The above sample uses the `EchoExporter` to dump trace results to the
-bottom of the webpage.
+## Usage
 
-If you would like to provide your own reporter, create a class that implements `ExporterInterface`.
-
-#### Currently implemented reporters
-
-| Class | Description |
-| ----- | ----------- |
-| [EchoExporter](src/Trace/Exporter/EchoExporter.php) | Output the collected spans to stdout |
-| [FileExporter](src/Trace/Exporter/FileExporter.php) | Output JSON encoded spans to a file |
-| [StackdriverExporter](src/Trace/Exporter/StackdriverExporter.php) | Report traces to Google Cloud Stackdriver Trace |
-| [LoggerExporter](src/Trace/Exporter/LoggerExporter.php) | Exporter JSON encoded spans to a PSR-3 logger |
-| [NullExporter](scr/Trace/Exporter/NullExporter.php) | No-op |
-| [ZipkinExporter](src/Trace/Exporter/ZipkinExporter.php) | Report collected spans to a Zipkin server |
-
-### Sampling Rate
-
-By default we attempt to trace all requests. This is not ideal as it adds a little bit of
-latency and require more memory for requests that are traced. To trace only a sampling
-of requests, configure a sampler.
-
-The preferred sampler is the `QpsSampler` (Queries Per Second). This sampler implementation
-requires a PSR-6 cache implementation to function.
-
-```php
-use OpenCensus\Trace\Exporter\EchoExporter;
-use OpenCensus\Trace\Sampler\QpsSampler;
-
-$cache = new SomeCacheImplementation();
-$sampler = new QpsSampler($cache, ['rate' => 0.1]); // sample 0.1 requests per second
-RequestTracer::start(new EchoExporter(), ['sampler' => $sampler]);
-```
-
-Please note: While required for the `QpsSampler`, a PSR-6 implementation is
-not included in this library. It will be necessary to include a separate
-dependency to fulfill this requirement. For PSR-6 implementations, please see the
-[Packagist PHP Package Repository](https://packagist.org/providers/psr/cache-implementation).
-If the APCu extension is available (available on Google AppEngine Flexible Environment)
-and you include the cache/apcu-adapter composer package, we will set up the cache for you.
-
-You can also choose to use the `ProbabilitySampler` which simply samples a flat
-percentage of requests.
-
-#### Currently implemented samplers
-
-| Class | Description |
-| ----- | ----------- |
-| [NeverSampleSampler](src/Trace/Sampler/NeverSampleSampler.php) | Never trace any requests |
-| [AlwaysSampleSampler](src/Trace/Sampler/AlwaysSampleSampler.php) | Trace all requests |
-| [QpsSampler](src/Trace/Sampler/QpsSampler.php) | Trace X requests per second. Requires a PSR-6 cache implementation |
-| [ProbabilitySampler](src/Trace/Sampler/ProbabilitySampler.php) | Trace X percent of requests. |
-
-```php
-use OpenCensus\Trace\Exporter\EchoExporter;
-use OpenCensus\Trace\Sampler\ProbabilitySampler;
-
-$sampler = new ProbabilitySampler(0.1); // sample 10% of requests
-RequestTracer::start(new EchoExporter(), ['sampler' => $sampler]);
-```
-
-If you would like to provide your own sampler, create a class that implements `SamplerInterface`.
-
-## Tracing Code Blocks
-
-To add tracing to a block of code, you can use the closure/callable form or explicitly open
-and close spans yourself.
+To add tracing to a block of code, you can use the closure/callable form or
+explicitly open and close spans yourself.
 
 ### Closure/Callable (preferred)
 
 ```php
-$pi = RequestTracer::inSpan(['name' => 'expensive-operation'], function() {
+$pi = Tracer::inSpan(['name' => 'expensive-operation'], function() {
     // some expensive operation
     return calculatePi(1000);
 });
 
-$pi = RequestTracer::inSpan(['name' => 'expensive-operation'], 'calculatePi', [1000]);
+$pi = Tracer::inSpan(['name' => 'expensive-operation'], 'calculatePi', [1000]);
 ```
 
 ### Explicit Span Management
 
 ```php
 // Creates a detached span
-$span = RequestTracer::startSpan(['name' => 'expensive-operation']);
+$span = Tracer::startSpan(['name' => 'expensive-operation']);
 
 // Opens a scope that attaches the span to the current context
-$scope = RequestTracer::withSpan($span);
+$scope = Tracer::withSpan($span);
 try {
     $pi = calculatePi(1000);
 } finally {
@@ -137,29 +70,48 @@ try {
 }
 ```
 
-### OpenCensus extension
+## Customization
 
-The `opencensus` extension collects nested span data throughout the course of your application's
-execution. You can collect spans in 2 ways, by watching for function/method invocations or by manually
-starting and stopping spans. In both cases, the spans will be collected together and can be retrieved
-at the end of the request.
+### Samplers
 
-See [extension README](ext/README.md) for more information.
+You can specify different samplers when initializing a tracer. The default
+sampler is the `AlwaysSampleSampler` which will attempt to trace all requests.
 
-## Versioning
+The provided samplers are:
 
-You can retrieve the version of this extension at runtime.
+| Class | Description |
+| ----- | ----------- |
+| [NeverSampleSampler][never-sampler] | Never trace any requests |
+| [AlwaysSampleSampler][always-sampler] | Trace all requests |
+| [QpsSampler][qps-sampler] | Trace X requests per second. Requires a PSR-6 cache implementation |
+| [ProbabilitySampler][probability-sampler] | Trace X percent of requests. |
 
-```php
-/**
- * Return the current version of the opencensus_trace extension
- *
- * @return string
- */
-function opencensus_trace_version();
-```
+If you would like to provide your own sampler, create a class that implements
+`SamplerInterface`.
 
-This library follows [Semantic Versioning](http://semver.org/).
+### Exporters
+
+You can choose different exporters to send the collected traces to.
+
+The provided exporters are:
+
+| Class | Description |
+| ----- | ----------- |
+| [EchoExporter][echo-exporter] | Output the collected spans to stdout |
+| [FileExporter][file-exporter] | Output JSON encoded spans to a file |
+| [StackdriverExporter][stackdriver-exporter] | Report traces to Google Cloud Stackdriver Trace |
+| [LoggerExporter][logger-exporter] | Exporter JSON encoded spans to a PSR-3 logger |
+| [NullExporter][null-exporter] | No-op |
+| [ZipkinExporter][zipkin-exporter] | Report collected spans to a Zipkin server |
+
+If you would like to provide your own reporter, create a class that implements
+`ExporterInterface`.
+
+## Versioning
+
+[![Packagist](https://img.shields.io/packagist/v/opencensus/opencensus.svg)](https://packagist.org/packages/opencensus/opencensus)
+
+This library follows [Semantic Versioning][semver].
 
 Please note it is currently under active development. Any release versioned
 0.x.y is subject to backwards incompatible changes at any time.
@@ -175,6 +127,9 @@ and requests with a higher priority.
 **Alpha**: Libraries defined at an Alpha quality level are still a
 work-in-progress and are more likely to get backwards-incompatible updates.
 
+**Current Status:** Pre-Alpha
+
+
 ## Contributing
 
 Contributions to this library are always welcome and highly encouraged.
@@ -192,3 +147,19 @@ Apache 2.0 - See [LICENSE](LICENSE) for more information.
 ## Disclaimer
 
 This is not an official Google product.
+
+[census-org]: https://github.com/census-instrumentation
+[api-docs]: http://opencensus.io/opencensus-php/
+[composer]: https://getcomposer.org/
+[pecl]: https://pecl.php.net/
+[never-sampler]: http://opencensus.io/opencensus-php/OpenCensus/Trace/Sampler/NeverSampleSampler.html
+[always-sampler]: http://opencensus.io/opencensus-php/OpenCensus/Trace/Sampler/NeverSampleSampler.html
+[qps-sampler]: http://opencensus.io/opencensus-php/OpenCensus/Trace/Sampler/NeverSampleSampler.html
+[probability-sampler]: http://opencensus.io/opencensus-php/OpenCensus/Trace/Sampler/NeverSampleSampler.html
+[echo-exporter]: http://opencensus.io/opencensus-php/OpenCensus/Trace/Exporter/EchoExporter.html
+[file-exporter]: http://opencensus.io/opencensus-php/OpenCensus/Trace/Exporter/FileExporter.html
+[stackdriver-exporter]: http://opencensus.io/opencensus-php/OpenCensus/Trace/Exporter/StackdriverExporter.html
+[logger-exporter]: http://opencensus.io/opencensus-php/OpenCensus/Trace/Exporter/LoggerExporter.html
+[null-exporter]: http://opencensus.io/opencensus-php/OpenCensus/Trace/Exporter/NullExporter.html
+[zipkin-exporter]: http://opencensus.io/opencensus-php/OpenCensus/Trace/Exporter/ZipkinExporter.html
+[semver]: http://semver.org/

config/sami.php

@@ -18,6 +18,10 @@
 use Sami\Sami;
 // use Sami\Version\GitVersionCollection;
 use Symfony\Component\Finder\Finder;
+use Sami\Parser\Filter\FilterInterface;
+use Sami\Reflection\ClassReflection;
+use Sami\Reflection\MethodReflection;
+use Sami\Reflection\PropertyReflection;
 
 $root_dir = __DIR__ . '/../';
 
@@ -30,7 +34,31 @@
 //     ->addFromTags('v0.*')
 //     ->add('master', 'master branch');
 
-return new Sami($iterator, [
+$sami = new Sami($iterator, [
     // 'versions'  => $versions,
-    'build_dir' => __DIR__ . '/../docs'
+    'build_dir' => __DIR__ . '/../docs',
+    'title' => 'OpenCensus PHP API'
 ]);
+
+class VisibleFilter implements FilterInterface
+{
+    public function acceptClass(ClassReflection $class)
+    {
+        return true;
+    }
+
+    public function acceptMethod(MethodReflection $method)
+    {
+        return !$method->isPrivate() && empty($method->getTags('internal'));
+    }
+    public function acceptProperty(PropertyReflection $property)
+    {
+        return !$property->isPrivate();
+    }
+}
+
+$sami['filter'] = function () {
+    return new \VisibleFilter();
+};
+
+return $sami;

src/Trace/Exporter/EchoExporter.php

@@ -22,6 +22,15 @@
 /**
  * This implementation of the ExporterInterface uses `print_r` to output
  * the trace's representation to stdout.
+ *
+ * Example:
+ * ```
+ * use OpenCensus\Trace\Exporter\EchoExporter;
+ * use OpenCensus\Trace\Tracer;
+ *
+ * $exporter = new EchoExporter();
+ * Tracer::begin($exporter);
+ * ```
  */
 class EchoExporter implements ExporterInterface
 {

src/Trace/Exporter/FileExporter.php

@@ -20,8 +20,17 @@
 use OpenCensus\Trace\Tracer\TracerInterface;
 
 /**
- * This implementation of the ExporterInterface appends a json
+ * This implementation of the ExporterInterface appends a JSON
  * representation of the trace to a file.
+ *
+ * Example:
+ * ```
+ * use OpenCensus\Trace\Exporter\FileExporter;
+ * use OpenCensus\Trace\Tracer;
+ *
+ * $exporter = new FileExporter('/path/to/file.txt');
+ * Tracer::begin($exporter);
+ * ```
  */
 class FileExporter implements ExporterInterface
 {

src/Trace/Exporter/LoggerExporter.php

@@ -21,8 +21,20 @@
 use Psr\Log\LoggerInterface;
 
 /**
- * This implementation of the ExporterInterface appends a json
- * representation of the trace to a file.
+ * This implementation of the ExporterInterface sends log messages to a
+ * configurable PSR-3 logger.
+ *
+ * Example:
+ * ```
+ * use OpenCensus\Trace\Exporter\LoggerExporter;
+ * use OpenCensus\Trace\Tracer;
+ * use Monolog\Logger;
+ *
+ * // Example PSR-3 logger
+ * $logger = new Logger('traces');
+ * $exporter = new LoggerExporter($logger);
+ * Tracer::begin($exporter);
+ * ```
  */
 class LoggerExporter implements ExporterInterface
 {

src/Trace/Exporter/NullExporter.php

@@ -21,6 +21,15 @@
 
 /**
  * This implementation of the ExporterInterface does nothing.
+ *
+ * Example:
+ * ```
+ * use OpenCensus\Trace\Exporter\NullExporter;
+ * use OpenCensus\Trace\Tracer;
+ *
+ * $exporter = new NullExporter();
+ * Tracer::begin($exporter);
+ * ```
  */
 class NullExporter implements ExporterInterface
 {