Tweak documentation (#21)

* Tweak documentation

* Fix a typo

Author: tkf

examples/lift-macro.jl

@@ -1,4 +1,4 @@
-# # [`@?` tutorial](@id tutorial)
+# # [How to use `@?`](@id tutorial)
 
 using Maybe
 
@@ -16,7 +16,7 @@ findfirst(x -> gcd(x, 42) == 21, 50:200)
 
 @assert findlast(x -> gcd(x, 42) == 23, 50:200) === nothing
 
-# Using such functions is rather tedious
+# It is rather tedious to combine such functions:
 
 function find_some_random_range_1(data)
     f(x) = gcd(x, 42) == 21

src/docs/@?.md

@@ -7,8 +7,8 @@ Idea:
 * Each function `f(::T₁, ..., ::Tₙ) -> ::R` is (conceptually) lifted to
   `f′(::Union{Some{T₁}, Nothing}, ..., ::Union{Some{Tₙ}, Nothing})
   -> ::Union{Some{R}, R, Nothing}`.
-* If any of the argument is `nothing`, `@?` short-circuits and
-  evaluates to `nothing`.
+* If any of the returned value is `nothing`, the evaluation of `expr`
+  in `@?` short-circuits and evaluates to `nothing`.
 
 See the [tutorial](@ref) for more information.
 
@@ -24,8 +24,7 @@ Some(3)
 julia> @? dict[:a][:b] + dict[:c]  # => nothing
 ```
 
-The expression in `@?` short-circuits when `nothing` appears in the
-argument position:
+The expression in `@?` short-circuits when a call returns `nothing`:
 
 ```jldoctest; setup = :(using Maybe)
 julia> f() = nothing;

src/docs/maybe.md

@@ -1,8 +1,8 @@
     maybe(f) -> f′
 
 Transform ("lift") function `f(::T₁, ..., ::Tₙ) -> ::Union{Some{R}, R,
-Nothing}` to `f′(::Union{Some{T₁}, Nothing}, ..., ::Union{Some{Tₙ},
-Nothing}) -> ::Union{Some{R}, Nothing}`.
+Nothing}` to `f′(::Union{T₁, Some{T₁}, Nothing}, ..., ::Union{Tₙ,
+Some{Tₙ}, Nothing}) -> ::Union{Some{R}, Nothing}`.
 
 # Examples
 ```jldoctest