document return nothing convention in Functions man page

[pierre-haessig]

Hi,

This short PR is a follow-up on a forum discussion about where return nothing convention should be documented.

As discussed, I documented this convention at the end of the section on return.

I also added some links to the style guide (the ! convention) and Methods chapters.

Somehow unrelated, I added two lines to explicitate the very first function example, because for a Julia newcomer like me, the implicit return is not self-evident.

Also, there was a URL typo in the Documentation README.

[GunnarFarneback]

Is it documented somewhere that return without a value is equivalent to return nothing?

[pierre-haessig]

I just learnt this shortcut from ScottPJones' reply on the forum.

[KristofferC]

Could be added to the return section in the Function chapter of the manual.

[JeffBezanson]

Yes it would be good to mention the equivalence of return and return nothing.

[pierre-haessig]

In the Functions page of the manual, I've added the equivalence of return, return nothing, as well as the possibility to just put nothing as the last expression.

Also, I've expanded the doc the return keyword itself, but it a much more compact way.

[pierre-haessig]

There is a build error because of a trailing whitespace in functions.md at line 177. Here it is:

julia> nothing
 

The problem comes from the blank line, where I indeed put one space character. If I remove it, the resulting html file will not contain a blank line, which makes this example pointless.

Now, on Github, blank lines are correctly displayed:

julia> nothing

Now this is the screenshot of the built doc, where the blank line is missing:

I've looked at the html code, but it's not so clear to me whether is an html or a css problem

[...] the REPL does not print anything for it:</p><pre><code class="language-julia-repl hljs"><span class="hljs-meta">julia&gt;</span><span class="julia"> <span class="hljs-literal">nothing</span>
</span></code></pre>

For comparison, this is the source of the Github-rendered html:

<pre lang="jldoctest"><code>julia&gt; nothing

</code></pre>

There is indeed one extra blank line. Maybe a bug with Documenter.jl ?

[fredrikekre]

html or a css problem

Neither, it's Documenter.jl: https://github.com/JuliaDocs/Documenter.jl/blob/a8a651e3bacd6380ebb2971af69a5070ad0a0a2e/src/Expanders.jl#L603-L611 Edit: Wrong reference

[pierre-haessig]

Ok, so it's Documenter.jl. Next question: is this a feature or a bug? And side question: if it's a bug and gets fixed, how much other doc pages will break ?!!

[fredrikekre]

Next question: is this a feature or a bug? And side question: if it's a bug and gets fixed, how much other doc pages will break ?!!

Probably just that no one thought about it before, shouldn't break anything.

[pierre-haessig]

Is there any change needed on the PR?

[pierre-haessig]

Is my doc update fine for merging or is there more work left (e.g. rebase) ?

Best, Pierre

[KristofferC]

I think we can remove the c comparison. It is a bit different imo since in c you explicitly declare the return type.

[KristofferC]

same here

[KristofferC]

Does this fit under the return nothing header?

[pierre-haessig]

After one year, the codebase has changed making part of my PR unrelevant. Still the core of the change would be useful I think. Since I'm not good at cherrypicking git commits, I'll close the PR and reopen a new one, with a reduced set of changes.