Include example and docs for Maybe

Author: TeamSpen210

docs/source/api.rst

@@ -16,6 +16,14 @@ API Reference
 
 .. py:data:: Maybe
    :value: Value[T] | Error
+A convenience alias to a union of both results. This allows type checkers to perform
+exhaustiveness checking when ``isinstance()`` is used with either class::
+
+    outcome: Maybe[int] = capture(some_function, 1, 2, 3)
+    if isinstance(outcome, Value):
+        # Type checkers know it's a Value[int] here.
+    else:
+        # It must be an Error.
 
 .. autoclass:: Value
    :members:

src/outcome/_impl.py

@@ -235,8 +235,5 @@ async def asend(self, agen: AsyncGenerator[ResultT, NoReturn]) -> ResultT:
         return await agen.athrow(self.error)
 
 
+# A convenience alias to a union of both results, allowing exhaustiveness checking.
 Maybe = Union[Value[ValueT], Error]
-"""
-A convenience alias to a union of both results. This allows type checkers to perform
-exhaustiveness checking when ``isinstance()`` is used with either class.
-"""