Update docblocks

lib/Coroutine.php

@@ -5,6 +5,12 @@ namespace Amp;
 use Interop\Async\Awaitable;
 use Interop\Async\Loop;
 
+/**
+ * Creates an awaitable from a generator function yielding awaitables. When an awaitable is yielded, execution of the
+ * generator is interrupted until the awaitable is resolved. The success value is sent to the generator, while the
+ * failure reason is thrown into the generator. Using a coroutine, asynchronous code can be written without callbacks
+ * and be structured like synchronous code.
+ */
 final class Coroutine implements Awaitable {
     use Internal\Placeholder;
 

lib/Failure.php

@@ -5,7 +5,10 @@ namespace Amp;
 use Interop\Async\Loop;
 use Interop\Async\Awaitable;
 
-class Failure implements Awaitable {
+/**
+ * Creates a failed awaitable using the given exception.
+ */
+final class Failure implements Awaitable {
     /**
      * @var \Exception|\Throwable $exception
      */

lib/Internal/CoroutineResult.php

@@ -2,6 +2,11 @@
 
 namespace Amp\Internal;
 
+/**
+ * Used in PHP 5.x to represent coroutine return values. Use the return keyword in PHP 7.x.
+ *
+ * @internal
+ */
 class CoroutineResult
 {
     /**

lib/Internal/LazyAwaitable.php

@@ -6,6 +6,11 @@ use Amp\Failure;
 use Amp\Success;
 use Interop\Async\Awaitable;
 
+/**
+ * Awaitable returned from Amp\lazy(). Use Amp\lazy() instead of instigating this object directly.
+ *
+ * @internal
+ */
 class LazyAwaitable implements Awaitable {
     /**
      * @var callable|null

lib/Internal/Placeholder.php

@@ -6,6 +6,12 @@ use Amp\Failure;
 use Interop\Async\Awaitable;
 use Interop\Async\Loop;
 
+/**
+ * Trait used by Awaitable implementations. Do not use this trait in your code, instead compose your class from one of
+ * the available classes implementing \Interop\Async\Awaitable.
+ *
+ * @internal
+ */
 trait Placeholder {
     /**
      * @var bool

lib/Internal/PrivateAwaitable.php

@@ -6,6 +6,8 @@ use Interop\Async\Awaitable;
 
 /**
  * An awaitable that cannot be externally resolved. Used by Deferred in development mode.
+ *
+ * @internal
  */
 final class PrivateAwaitable implements Awaitable {
     use Placeholder;

lib/Internal/WhenQueue.php

@@ -4,6 +4,11 @@ namespace Amp\Internal;
 
 use Interop\Async\Loop;
 
+/**
+ * Stores a set of functions to be invoked when an awaitable is resolved.
+ *
+ * @internal
+ */
 class WhenQueue {
     /**
      * @var callable[]

lib/Pause.php

@@ -5,7 +5,10 @@ namespace Amp;
 use Interop\Async\Awaitable;
 use Interop\Async\Loop;
 
-class Pause implements Awaitable {
+/**
+ * Creates an awaitable that resolves itself with a given value after a number of milliseconds.
+ */
+final class Pause implements Awaitable {
     use Internal\Placeholder;
 
     /**

lib/Success.php

@@ -5,7 +5,11 @@ namespace Amp;
 use Interop\Async\Loop;
 use Interop\Async\Awaitable;
 
-class Success implements Awaitable {
+/**
+ * Creates a successful awaitable using the given value (which can be any value except another object implementing
+ * \Interop\Async\Awaitable).
+ */
+final class Success implements Awaitable {
     /**
      * @var mixed
      */