Roll up #29389

Author: mark-summerfield

doc/src/manual/functions.md

@@ -1,7 +1,7 @@
 # [Functions](@id man-functions)
 
 In Julia, a function is an object that maps a tuple of argument values to a return value. Julia
-functions are not pure mathematical functions, in the sense that functions can alter and be affected
+functions are not pure mathematical functions, because they can alter and be affected
 by the global state of the program. The basic syntax for defining functions in Julia is:
 
 ```jldoctest
@@ -35,7 +35,7 @@ julia> f(2,3)
 ```
 
 Without parentheses, the expression `f` refers to the function object, and can be passed around
-like any value:
+like any other value:
 
 ```jldoctest fofxy
 julia> g = f;
@@ -241,7 +241,7 @@ as arguments. A classic example is [`map`](@ref), which applies a function to ea
 an array and returns a new array containing the resulting values:
 
 ```jldoctest
-julia> map(round, [1.2,3.5,1.7])
+julia> map(round, [1.2, 3.5, 1.7])
 3-element Array{Float64,1}:
  1.0
  4.0
@@ -254,7 +254,7 @@ situations, the anonymous function construct allows easy creation of a single-us
 without needing a name:
 
 ```jldoctest
-julia> map(x -> x^2 + 2x - 1, [1,3,-1])
+julia> map(x -> x^2 + 2x - 1, [1, 3, -1])
 3-element Array{Int64,1}:
   2
  14
@@ -317,15 +317,19 @@ The components of tuples can optionally be named, in which case a *named tuple*
 constructed:
 
 ```jldoctest
-julia> x = (a=1, b=1+1)
-(a = 1, b = 2)
+julia> x = (a=2, b=1+2)
+(a = 2, b = 3)
+
+julia> x[1]
+2
 
 julia> x.a
-1
+2
 ```
 
 Named tuples are very similar to tuples, except that fields can additionally be accessed by name
-using dot syntax (`x.a`).
+using dot syntax (`x.a`) in addition to the regular indexing syntax
+(`x[1]`).
 
 ## Multiple Return Values
 
@@ -363,7 +367,7 @@ julia> y
 6
 ```
 
-You can also return multiple values via an explicit usage of the `return` keyword:
+You can also return multiple values using the `return` keyword:
 
 ```julia
 function foo(a,b)
@@ -508,8 +512,9 @@ call will fail, just as it would if too many arguments were given explicitly.
 
 ## Optional Arguments
 
-In many cases, function arguments have sensible default values and therefore might not need to
-be passed explicitly in every call. For example, the function [`Date(y, [m, d])`](@ref)
+It is often possible to provide sensible default values for function arguments.
+This can save users from having to pass every argument on every call.
+For example, the function [`Date(y, [m, d])`](@ref)
 from `Dates` module constructs a `Date` type for a given year `y`, month `m` and day `d`.
 However, `m` and `d` arguments are optional and their default value is `1`.
 This behavior can be expressed concisely as:
@@ -522,11 +527,11 @@ function Date(y::Int64, m::Int64=1, d::Int64=1)
 end
 ```
 
-Observe, that this definition calls another method of `Date` function that takes one argument
-of `UTInstant{Day}` type.
+Observe, that this definition calls another method of the `Date` function that takes one argument
+of type `UTInstant{Day}`.
 
 With this definition, the function can be called with either one, two or three arguments, and
-`1` is automatically passed when any of the arguments is not specified:
+`1` is automatically passed when only one or two of the arguments are specified:
 
 ```jldoctest
 julia> using Dates
@@ -792,8 +797,8 @@ julia> sin.(A)
 ```
 
 Of course, you can omit the dot if you write a specialized "vector" method of `f`, e.g. via `f(A::AbstractArray) = map(f, A)`,
-and this is just as efficient as `f.(A)`. But that approach requires you to decide in advance
-which functions you want to vectorize.
+and this is just as efficient as `f.(A)`. The advantage of the `f.(A)` syntax is that which functions are vectorizable need not be decided upon
+in advance by the library writer.
 
 More generally, `f.(args...)` is actually equivalent to `broadcast(f, args...)`, which allows
 you to operate on multiple arrays (even of different shapes), or a mix of arrays and scalars (see