docs: add descriptions and examples to api

README.md

@@ -28,7 +28,7 @@ function getUsername(): string | undefined {
 
 let normalizedUsername = 'username';
 const username = getUsername();
-if (username === undefined) {
+if (username !== undefined) {
     const firstName = username.split(' ')[0];
     normalizedUsername = firstName.toLowerCase();
 }
@@ -37,13 +37,28 @@ if (username === undefined) {
 ## Api
 
 ### map
+Map gives access to the contained value.
+Imagine an array, `Array<string>`, as a container for strings, the `map` function applies a function to each element if the container is not empty and gives back a new container.
+For instance:
+```typescript
+const orig: Array<string> = ['1', '2', '3'];
+const now: Array<number> = orig.map(x => parseInt(x));
+```
+
 ```typescript
     some('thing').map(v => console.log(v)) // prints "thing"
 
     none().map(v => console.log(v)) // does not print
 ```
 
 ### flatMap
+FlatMap also accesses the contained value, but it expects that its "mapper" function returns a container of the same type.
+Imagine the conceptually equivalent array container:
+```typescript
+const orig: Array<number> = [1, 3, 5];
+const now: Array<number> = orig.flatMap(x => ( [x, x + 1] ));
+console.log(now); // => [1, 2, 3, 4, 5, 6]
+```
 ```typescript
 const maybeAdd1 = (x: Maybe<number>) => x.map(y => y + 1);
 
@@ -53,6 +68,9 @@ const y = none().flatMap(maybeAdd1); // Maybe<undefined>
 ```
 
 ### or
+Similar to the `or` logical operator.
+Tries to get the value (true) of the first maybe; if it is empty (false), tries to get the value (true) of the second maybe.
+If both are empty (false), returns an empty (false) maybe.
 ```typescript
 const first = none();
 const second = some(22);
@@ -61,6 +79,13 @@ const third = first.or(second); // Maybe<22>
 ```
 
 ### orElse
+Similar to `or`, except the second value is not allowed to be empty.
+`orElse` _must_ return an instance of the contained value, even if the maybe is empty.
+This is useful for supplying default values:
+```typescript
+const maybeName = maybe(getNameFromInput());
+const name = maybeName.orElse('enter name please');
+```
 ```typescript
 const first = none<string>();
 const second = 'hi';
@@ -69,6 +94,20 @@ const third = first.orElse(second); // 'hi';
 ```
 
 ### expect
+`expect` forcefully gets the value out of the `Maybe` container, or throws an error if there is no value.
+This is useful whenever you _know_ the value must be defined at this point, and you want to get out of the `Maybe` chain.
+For instance:
+```typescript
+function tryOption1(): Maybe<string> { ... }
+function tryOption2(): Maybe<string> { ... }
+function tryOption3(): Maybe<string> { ... } // The string must be created by one of these 3, we just don't know which
+
+const str: string =
+    tryOption1()
+        .or(tryOption2)
+        .or(tryOption3)
+        .expect('We expected to get the from one of these three methods');
+```
 ```typescript
 function getData(): Maybe<DataType> { ... }
 const maybeData = getData();
@@ -79,6 +118,15 @@ const shouldHaveData = maybeData.expect("oops, guess I didn't");
 ```
 
 ### caseOf
+`caseOf` is a pattern matcher for the `Maybe`.
+This is useful when you want to execute different logic dependent on whether the container is empty.
+For instance:
+```typescript
+maybeData.caseOf({
+    none: () => attemptToGetFromApi().map(doThingWithData),
+    some: data => doThingWithData(data),
+});
+```
 ```typescript
 getData().caseOf({
     some: value => value + 1,
@@ -89,6 +137,16 @@ getData().caseOf({
 ```
 
 ### asNullable
+`asNullable` provides an "out" for escaping the `Maybe` container.
+This is particularly useful at the boundaries of your API.
+Often the internals of a library use `Maybe` to clean up code, but would like their external contracts to not be forced to use `Maybe`s, but instead "vanilla" JS.
+For instance:
+```typescript
+export function doThing(): string | undefined {
+    const maybeValue: Maybe<string> = getFromSomewhereInLib();
+    return maybeValue.asNullable();
+}
+```
 ```typescript
 const value = 'hi';
 const nullable = maybe(value).asNullable();