Clarify Promise::when docblock

It specifies the exact invocation parameter values now and includes a statement about always-sync when callbacks.

Closes #20.

Author: kelunik

src/Promise.php

@@ -10,7 +10,14 @@ interface Promise
     /**
      * Registers a callback to be invoked when the promise is resolved.
      *
-     * @param callable(\Throwable|\Exception|null $exception, mixed $result) $onResolved
+     * The callback receives `null` as first parameter and `$value` as second parameter on success. It receives the
+     * failure reason as first parameter and `null` as second parameter on failure.
+     *
+     * If the promise is already resolved, the callback MUST be executed immediately.
+     *
+     * Warning: If you use type declarations for `$value`, be sure to make them accept `null` in case of failures.
+     *
+     * @param callable(\Throwable|\Exception|null $exception, mixed $value) $onResolved Callback to be executed.
      *
      * @return void
      */