Replace -> with :: where appropriate in docstrings

[LilithHafner]

In cases where a function is documented as

```
    function(arg::ArgT, arg2::Arg2T) -> RetT

...
```

I either switched -> to :: or switched RetT to ret_name::RetT.

From the recommendation and justification from @nsajko here: #56978 (comment) and applied throughout the repo.

[mcabbott]

At some point I made a branch switching to --> instead (but never made a PR). One of the goals was things like this, where what is returned seems more important than the type:

lmul!(a::Number, B::AbstractArray) --> B     # mutates & returns 2nd arg

eigvals!(A, B; sortby) --> values::Vector    # returns neither arg

I see the PR would make these eigvals!(A, B; sortby) -> values::Vector. Perhaps that seems awkwardly almost-code (same complaint as the present ->)? My idea was to make a smaller visual change, and move in the direction of clearly-not-syntax.

I also had these... which do parse as capturing :(s --> Bool) but at least --> has no definition, while s::Bool does mean something which isn't true:

@isdefined s --> Bool

 @__LINE__ --> Int

[mcabbott]

or switched ... to ret_name::RetT.

Took a while to find an example of what exactly this meant.

If the reason to use :: is that this is valid syntax, does this want to use -> when it's not?

[mcabbott]

Should cases like this be annotated at all, or is it just clutter?

The default assumption that SomeType(...) must construct a SomeType, exceptions (at there any?) need a giant warning. Annotating all the normal cases, if anything, seems to hint that there might be exceptions to watch out for.

[LilithHafner]

Yeah, I agree with you: Just clutter.

[mcabbott]

This parses as calling the macro on :(s::Bool), which isn't great. (The old one parsed a a function of course, but the point of the PR is to remove that.)

[LilithHafner]

Yep! I intended to skip macros in this PR but accidentally included that. Should be fixed (probably just reverted/left alone)

[jmert]

At some point I made a branch switching to --> instead (but never made a PR). One of the goals was things like this, where what is returned seems more important than the type:

lmul!(a::Number, B::AbstractArray) --> B     # mutates & returns 2nd arg

eigvals!(A, B; sortby) --> values::Vector    # returns neither arg

What about using assignment syntax to name variables instead?

B = lmul!(a::Number, B::AbstractArray)

values = eigvals!(A, B; sortby)::Vector

maxval, index = findmax(A; dims)

[jishnub]

Previous discussion on this at #22804

[LilithHafner]

Reading the previous discussion and existing docstrings, I propose that :: is used to indicate return types and -> is used to indicate return values, following these patterns:

    f(x::T)::U
    f(x::T) -> y::U
    f(x::T) -> (y::U1, z::U2)
    f(x::T)::Tuple{U1, U2} # valid and reasonable, but I'd prefer the option above 
    @mac x -> y::U
    @mac -> y::U
    @mac::U # Not this, it's not valid syntax
    @mac -> U # Also not this, it's inconsistent with the forms above. Provide a variable name for the output.
    U(x::T) # Don't annotate the return type if it's obvious

[laborg]

I like the idea from @mbauman to use → instead of -> to distinguish it from anonymous functions. If this is used, I'd also prefer having it consistently, even if only the type is specified:

f(x::T) ⇥ # when nothing is returned
f(x::T) → ::U
f(x::T) → y::U
f(x::T) → (y::U1, z::U2)
f(x::T) → ::Tuple{U1, U2}