document return nothing in Functions man page (2nd PR)

[pierre-haessig]

Hi,

This is my 2nd try to document the return nothing convention in the Functions manual. My first PR #27286 was 1 year old, so that some of my changes became superfluous (in particular, the documentation of return in base/docs/basedocs.jl now does mention nothing thanks to PR #30716).

Still, the Functions manual lacks the changes I proposed. Here a more compact PR, which answers @KristofferC feedback (e.g. I removed any reference to C's return;). The increased compactness should hopefully make it easier to merge!

I kept only one offtopic change: in the first PR, I was updating the link to Markdown syntax in doc/ README.md. In the meantime, it was changed, but it's again broken, so here is a one line fix which may not deserve a PR of its own.

[KristofferC]

This is slightly at odds with the convention to return the modified object as in

julia> a = rand(2); push!(a, 2.0)
3-element Array{Float64,1}:
 0.7926734563461015
 0.6590165997556594
 2.0 

[pierre-haessig]

Indeed. In fact I copy pastd this fragment from the FAQ. What do you thinkg of:

For functions which do not need to return a value, the Julia convention is to return the value nothing
...

[StefanKarpinski]

Might be good to use an expression here that doesn't already evaluate to nothing.

[pierre-haessig]

Ok, I understand you see this example as contrived because it would be equivalent without the return nothing line, is this correct? Indeed I hadn't thought of that. One way would be to write down this remark. As for another example, do you have any idea?

Instead of a display function (I guess that all display functions other than println will also return nothing), we could use a function which sets some global variable like

function setflag(a)
    global flag
    flag = a
    return nothing
end

However, this kind of function may more likely return the new value rather than nothing. Also, the global keyword is introduced two chapters later (if we consider the manual to be a sequential reading). What do you think?

[pierre-haessig]

I've added a commit in response of both @KristofferC (functions with side effects) and @StefanKarpinski (contrived example) comments.

[pierre-haessig]

There are some builbot errors, but it's not clear to me if it relates to the PR.

[kshyatt]

In freebsd, it was Distributed which broke which should be unrelated.
In osx64, it was FileWatching which is also iirc a notorious problem, but should be unrelated.
Win64 timed out with no output.

Is this ready to go?

[pierre-haessig]

Now that @JeffBezanson comment is adressed, I believe the PR may be merged (unless some builbot errors appear).

[pierre-haessig]

Thanks! This truely closes #27286.