Added documentation for callable syntax

docs/supported_annotations.md

@@ -16,6 +16,7 @@ Psalm supports a wide range of docblock annotations.
 - [Type Syntax](#type-syntax)
   - [Class constants](#class-constants)
   - [Object-like arrays](#object-like-arrays)
+  - [Callables and Closures](#callables-and-closures)
 
 ## PHPDoc tags
 
@@ -221,3 +222,28 @@ function foo(array $arr): void {
 foo(["cool", 4]); // passes
 foo([4, "cool"]); // fails
 ```
+### Callables and Closures
+
+Psalm supports a special format for `callable`s of the form
+
+```
+callable(Type1, OptionalType2=, ...SpreadType3):ReturnType
+```
+
+Using this annotation you can specify that a given function return a `Closure` e.g.
+
+```php
+/**
+ * @return Closure(bool):int
+ */
+function delayedAdd(int $x, int $y) : Closure {
+  return function(bool $debug) use ($x, $y) {
+    if ($debug) echo "got here" . PHP_EOL;
+    return $x + $y;
+  };
+}
+
+$adder = delayedAdd(3, 4);
+echo $adder(true);
+```
+