document return nothing convention in Functions man page

base/docs/basedocs.jl

@@ -333,6 +333,10 @@ function compare(a, b)
     a < b ? "less than" : "greater than"
 end
 ```
+
+If the returned value is omitted, `return` returns the value [`nothing`](@ref)
+(quite similar to C).
+
 In general you can place a `return` statement anywhere within a function body, including
 within deeply nested loops or conditionals, but be careful with `do` blocks. For
 example:

doc/README.md

@@ -1,6 +1,6 @@
 # Julia Documentation README
 
-Julia's documentation is written in Markdown. A reference of all supported syntax can be found in the [manual](https://docs.julialang.org/en/latest/manual/documentation/#markdown-syntax). All documentation can be found in the Markdown files in `doc/src/` and the docstrings in Julia source files in `base/`.
+Julia's documentation is written in Markdown. A reference of all supported syntax can be found in the [manual](https://docs.julialang.org/en/latest/manual/documentation#markdown-syntax). All documentation can be found in the Markdown files in `doc/src/` and the docstrings in Julia source files in `base/`.
 
 ## Requirements
 

doc/src/manual/faq.md

@@ -43,7 +43,7 @@ obj3 = MyModule.someotherfunction(obj2, c)
 
 ## Functions
 
-### I passed an argument `x` to a function, modified it inside that function, but on the outside, the variable `x` is still unchanged. Why?
+### [I passed an argument `x` to a function, modified it inside that function, but on the outside, the variable `x` is still unchanged. Why?](@id faq-arg-modif)
 
 Suppose you call a function like this:
 

doc/src/manual/functions.md

@@ -11,6 +11,9 @@ julia> function f(x,y)
 f (generic function with 1 method)
 ```
 
+This function accepts two arguments `x` and `y` and returns the value
+of the last expression evaluated, which is `x + y`.
+
 There is a second, more terse syntax for defining a function in Julia. The traditional function
 declaration syntax demonstrated above is equivalent to the following compact "assignment form":
 
@@ -56,16 +59,25 @@ julia> ∑(2, 3)
 Julia function arguments follow a convention sometimes called "pass-by-sharing", which means that
 values are not copied when they are passed to functions. Function arguments themselves act as
 new variable *bindings* (new locations that can refer to values), but the values they refer to
-are identical to the passed values. Modifications to mutable values (such as `Array`s) made within
-a function will be visible to the caller. This is the same behavior found in Scheme, most Lisps,
+are identical to the passed values.
+Consequently, assigning a new value to a function argument just rebinds it to that new value,
+but does not modify any variable in the caller scope.
+However, modifications to *mutable* values (such as `Array`s) made within
+a function will be visible to the caller.
+
+There is a dedicated [FAQ section](@ref faq-arg-modif) on how a function
+can or cannot modify its arguments, with a set of code examples.
+Julia argument passing behavior is the same behavior found in Scheme, most Lisps,
 Python, Ruby and Perl, among other dynamic languages.
 
+
 ## The `return` Keyword
 
 The value returned by a function is the value of the last expression evaluated, which, by default,
 is the last expression in the body of the function definition. In the example function, `f`, from
-the previous section this is the value of the expression `x + y`. As in C and most other imperative
-or functional languages, the `return` keyword causes a function to return immediately, providing
+the previous section this is the value of the expression `x + y`.
+As an alternative, as in most other languages,
+the `return` keyword causes a function to return immediately, providing
 an expression whose value is returned:
 
 ```julia
@@ -125,7 +137,9 @@ There are three possible points of return from this function, returning the valu
 expressions, depending on the values of `x` and `y`. The `return` on the last line could be omitted
 since it is the last expression.
 
-A return type can also be specified in the function declaration using the `::` operator. This converts
+### Return type
+
+A return type can be specified in the function declaration using the `::` operator. This converts
 the return value to the specified type.
 
 ```jldoctest
@@ -140,6 +154,41 @@ Int8
 This function will always return an `Int8` regardless of the types of `x` and `y`.
 See [Type Declarations](@ref) for more on return types.
 
+Incidentally, the type of the arguments can also be specified similarly,
+but this is the topic of the [Methods](@ref) chapter.
+
+### Returning nothing
+
+Some functions are used only for their side effects, and do not need to return a value.
+In these cases, the Julia convention is to return the value [`nothing`](@ref):
+
+```julia
+function printx(x)
+    println("x = $x")
+    return nothing
+end
+```
+
+Notice that `nothing` is not a Julia keyword but a singleton object of type `Nothing`.
+To support this convention, the REPL does not print anything for it:
+
+```jldoctest
+julia> nothing
+
+```
+
+There are two possible shortened forms for the `return nothing` expression.
+On the one hand, the `return` keyword implicitly returns `nothing`, so it can be used alone
+(similar in that sense to `return;` in C).
+On the other hand, since functions implicitly return their last expression evaluated,
+`nothing` can be used alone when it's the last exression.
+The preference for the expression `return nothing` as opposed to `return` or `nothing`
+alone is a subjective matter of coding style. Some people prefer explicitness
+(always specifying the returned value), while some others favor compactness.
+
+As a side note on functions with side effects, the [style guide](@ref man-style-exclam)
+recommends to append `!` to the names of functions that modify their arguments.
+
 ## Operators Are Functions
 
 In Julia, most operators are just functions with support for special syntax. (The exceptions are

doc/src/manual/style-guide.md

@@ -86,7 +86,7 @@ One issue here is that if a function inherently requires integers, it might be b
 the caller to decide how non-integers should be converted (e.g. floor or ceiling). Another issue
 is that declaring more specific types leaves more "space" for future method definitions.
 
-## Append `!` to names of functions that modify their arguments
+## [Append `!` to names of functions that modify their arguments](@id man-style-exclam)
 
 Instead of: