Issue Description:

This compiles:

            func f(s:String) -> Int { return 1 }
            _ = Optional("hello").flatMap(f)

Why? The declaration is:

func flatMap<U>(_ transform: (Wrapped) throws -> U?) rethrows -> U?

And the docs / comment say:

Use the `flatMap` method with a closure that returns an optional value

But `f` is not "a closure that returns an Optional value". It returns an Int, not an Optional<Int>. I would have thought we'd have to call `map`, not `flatMap`.

Basically what's going on here is that the docs are wrong, or at least very misleading. The docs seem to say that the distinction is between what kind of closure they take: one that produces an Optional, or one that does not. But that is quite false. They both accept either kind of closure. All of these expression compile just fine:

    let i : Int? = nil
    let result1 = i.map {_ in "hello"} // map, closure produces nonOptional
    let result2 = i.flatMap {_ in "hello"} // flatMap, closure produces nonOptional
    let result3 = i.map {_ in Optional("hello") } // map, closure produces Optional
    let result4 = i.flatMap {_ in Optional("hello") } // flatMap, closure produces Optional

Okay, so what's the actual difference? It's what `flatMap` does just in case the closure does produce an Optional: it unwraps it, thus preventing a doubly-wrapped Optional:

    let i : Int? = nil
    let result1 = i.map {_ in "hello"} // String?
    let result2 = i.flatMap {_ in "hello"} // String?
    let result3 = i.map {_ in Optional("hello") } // String?? // double-wrapped
    let result4 = i.flatMap {_ in Optional("hello") } // String? // not double-wrapped

Well, the docs should say that — and they don't.