Replace -> with :: where appropriate in docstrings (#57012)

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.

As documented here #57583

Also includes some minor changes to touched lines (e.g. removing annotations that are just clutter)

Author: LilithHafner

Compiler/src/abstractlattice.jl

@@ -153,23 +153,23 @@ function ⊑ end
 @nospecializeinfer ⊑(::JLTypeLattice, @nospecialize(a::Type), @nospecialize(b::Type)) = a <: b
 
 """
-    ⊏(𝕃::AbstractLattice, a, b) -> Bool
+    ⊏(𝕃::AbstractLattice, a, b)::Bool
 
 The strict partial order over the type inference lattice.
 This is defined as the irreflexive kernel of `⊑`.
 """
 @nospecializeinfer ⊏(𝕃::AbstractLattice, @nospecialize(a), @nospecialize(b)) = ⊑(𝕃, a, b) && !⊑(𝕃, b, a)
 
 """
-    ⋤(𝕃::AbstractLattice, a, b) -> Bool
+    ⋤(𝕃::AbstractLattice, a, b)::Bool
 
 This order could be used as a slightly more efficient version of the strict order `⊏`,
 where we can safely assume `a ⊑ b` holds.
 """
 @nospecializeinfer ⋤(𝕃::AbstractLattice, @nospecialize(a), @nospecialize(b)) = !⊑(𝕃, b, a)
 
 """
-    is_lattice_equal(𝕃::AbstractLattice, a, b) -> Bool
+    is_lattice_equal(𝕃::AbstractLattice, a, b)::Bool
 
 Check if two lattice elements are partial order equivalent.
 This is basically `a ⊑ b && b ⊑ a` in the lattice of `𝕃`
@@ -181,7 +181,7 @@ but (optionally) with extra performance optimizations.
 end
 
 """
-    has_nontrivial_extended_info(𝕃::AbstractLattice, t) -> Bool
+    has_nontrivial_extended_info(𝕃::AbstractLattice, t)::Bool
 
 Determines whether the given lattice element `t` of `𝕃` has non-trivial extended lattice
 information that would not be available from the type itself.
@@ -204,7 +204,7 @@ end
 @nospecializeinfer has_nontrivial_extended_info(::JLTypeLattice, @nospecialize(t)) = false
 
 """
-    is_const_prop_profitable_arg(𝕃::AbstractLattice, t) -> Bool
+    is_const_prop_profitable_arg(𝕃::AbstractLattice, t)::Bool
 
 Determines whether the given lattice element `t` of `𝕃` has new extended lattice information
 that should be forwarded along with constant propagation.

Compiler/src/ssair/domtree.jl

@@ -595,7 +595,7 @@ function rename_nodes!(D::DFSTree, rename_bb::Vector{BBNumber})
 end
 
 """
-    dominates(domtree::DomTree, bb1::Int, bb2::Int) -> Bool
+    dominates(domtree::DomTree, bb1::Int, bb2::Int)::Bool
 
 Checks if `bb1` dominates `bb2`.
 `bb1` and `bb2` are indexes into the `CFG` blocks.
@@ -606,7 +606,7 @@ dominates(domtree::DomTree, bb1::BBNumber, bb2::BBNumber) =
     _dominates(domtree, bb1, bb2)
 
 """
-    postdominates(domtree::PostDomTree, bb1::Int, bb2::Int) -> Bool
+    postdominates(domtree::PostDomTree, bb1::Int, bb2::Int)::Bool
 
 Checks if `bb1` post-dominates `bb2`.
 `bb1` and `bb2` are indexes into the `CFG` blocks.

Compiler/src/tfuncs.jl

@@ -2597,7 +2597,7 @@ const _EFFECTS_KNOWN_BUILTINS = Any[
 ]
 
 """
-    builtin_effects(𝕃::AbstractLattice, f::Builtin, argtypes::Vector{Any}, rt) -> Effects
+    builtin_effects(𝕃::AbstractLattice, f::Builtin, argtypes::Vector{Any}, rt)::Effects
 
 Compute the effects of a builtin function call. `argtypes` should not include `f` itself.
 """
@@ -2742,7 +2742,7 @@ current_scope_tfunc(interp::AbstractInterpreter, sv) = Any
 hasvarargtype(argtypes::Vector{Any}) = !isempty(argtypes) && isvarargtype(argtypes[end])
 
 """
-    builtin_nothrow(𝕃::AbstractLattice, f::Builtin, argtypes::Vector{Any}, rt) -> Bool
+    builtin_nothrow(𝕃::AbstractLattice, f::Builtin, argtypes::Vector{Any}, rt)::Bool
 
 Compute throw-ness of a builtin function call. `argtypes` should not include `f` itself.
 """

Compiler/src/types.jl

@@ -441,7 +441,7 @@ may_compress(::AbstractInterpreter) = true
 may_discard_trees(::AbstractInterpreter) = true
 
 """
-    method_table(interp::AbstractInterpreter) -> MethodTableView
+    method_table(interp::AbstractInterpreter)::MethodTableView
 
 Returns a method table this `interp` uses for method lookup.
 External `AbstractInterpreter` can optionally return `OverlayMethodTable` here
@@ -519,7 +519,7 @@ add_edges_impl(::Vector{Any}, ::CallInfo) = error("""
     All `CallInfo` is required to implement `add_edges_impl(::Vector{Any}, ::CallInfo)`""")
 nsplit_impl(::CallInfo) = nothing
 getsplit_impl(::CallInfo, ::Int) = error("""
-    A `info::CallInfo` that implements `nsplit_impl(info::CallInfo) -> Int` must implement `getsplit_impl(info::CallInfo, idx::Int) -> MethodLookupResult`
+    A `info::CallInfo` that implements `nsplit_impl(info::CallInfo)::Int` must implement `getsplit_impl(info::CallInfo, idx::Int)::MethodLookupResult`
     in order to correctly opt in to inlining""")
 getresult_impl(::CallInfo, ::Int) = nothing
 

Compiler/src/typeutils.jl

@@ -24,7 +24,7 @@ function hasuniquerep(@nospecialize t)
 end
 
 """
-    isTypeDataType(@nospecialize t) -> Bool
+    isTypeDataType(@nospecialize t)::Bool
 
 For a type `t` test whether ∀S s.t. `isa(S, rewrap_unionall(Type{t}, ...))`,
 we have `isa(S, DataType)`. In particular, if a statement is typed as `Type{t}`
@@ -303,7 +303,7 @@ end
 const unwraptv = unwraptv_ub
 
 """
-    is_identity_free_argtype(argtype) -> Bool
+    is_identity_free_argtype(argtype)::Bool
 
 Return `true` if the `argtype` object is identity free in the sense that this type or any
 reachable through its fields has non-content-based identity (see `Base.isidentityfree`).
@@ -316,7 +316,7 @@ is_identity_free_argtype(@nospecialize ty) = is_identity_free_type(widenconst(ig
 is_identity_free_type(@nospecialize ty) = isidentityfree(ty)
 
 """
-    is_immutable_argtype(argtype) -> Bool
+    is_immutable_argtype(argtype)::Bool
 
 Return `true` if the `argtype` object is known to be immutable.
 This query is specifically designed for `getfield_effects` and `isdefined_effects`, allowing
@@ -334,7 +334,7 @@ function _is_immutable_type(@nospecialize ty)
 end
 
 """
-    is_mutation_free_argtype(argtype) -> Bool
+    is_mutation_free_argtype(argtype)::Bool
 
 Return `true` if `argtype` object is mutation free in the sense that no mutable memory
 is reachable from this type (either in the type itself) or through any fields

Compiler/src/utilities.jl

@@ -174,14 +174,14 @@ isa_compileable_sig(m::ABIOverride) = false
 has_typevar(@nospecialize(t), v::TypeVar) = ccall(:jl_has_typevar, Cint, (Any, Any), t, v) != 0
 
 """
-    is_declared_inline(method::Method) -> Bool
+    is_declared_inline(method::Method)::Bool
 
 Check if `method` is declared as `@inline`.
 """
 is_declared_inline(method::Method) = _is_declared_inline(method, true)
 
 """
-    is_declared_noinline(method::Method) -> Bool
+    is_declared_noinline(method::Method)::Bool
 
 Check if `method` is declared as `@noinline`.
 """
@@ -195,14 +195,14 @@ function _is_declared_inline(method::Method, inline::Bool)
 end
 
 """
-    is_aggressive_constprop(method::Union{Method,CodeInfo}) -> Bool
+    is_aggressive_constprop(method::Union{Method,CodeInfo})::Bool
 
 Check if `method` is declared as `Base.@constprop :aggressive`.
 """
 is_aggressive_constprop(method::Union{Method,CodeInfo}) = method.constprop == 0x01
 
 """
-    is_no_constprop(method::Union{Method,CodeInfo}) -> Bool
+    is_no_constprop(method::Union{Method,CodeInfo})::Bool
 
 Check if `method` is declared as `Base.@constprop :none`.
 """

base/Base_compiler.jl

@@ -159,7 +159,7 @@ if false
 end
 
 """
-    time_ns() -> UInt64
+    time_ns()::UInt64
 
 Get the time in nanoseconds relative to some arbitrary time in the past. The primary use is for measuring the elapsed time
 between two moments in time.

base/abstractarray.jl

@@ -257,7 +257,7 @@ julia> Base.elsize(rand(Float32, 10))
 elsize(A::AbstractArray) = elsize(typeof(A))
 
 """
-    ndims(A::AbstractArray) -> Integer
+    ndims(A::AbstractArray)::Integer
 
 Return the number of dimensions of `A`.
 
@@ -276,7 +276,7 @@ ndims(::Type{<:AbstractArray{<:Any,N}}) where {N} = N::Int
 ndims(::Type{Union{}}, slurp...) = throw(ArgumentError("Union{} does not have elements"))
 
 """
-    length(collection) -> Integer
+    length(collection)::Integer
 
 Return the number of elements in the collection.
 
@@ -404,8 +404,8 @@ _all_match_first(f::F, inds) where F<:Function = true
 keys(s::IndexStyle, A::AbstractArray, B::AbstractArray...) = eachindex(s, A, B...)
 
 """
-    lastindex(collection) -> Integer
-    lastindex(collection, d) -> Integer
+    lastindex(collection)::Integer
+    lastindex(collection, d)::Integer
 
 Return the last index of `collection`. If `d` is given, return the last index of `collection` along dimension `d`.
 
@@ -427,8 +427,8 @@ lastindex(a::AbstractArray) = (@inline; last(eachindex(IndexLinear(), a)))
 lastindex(a, d) = (@inline; last(axes(a, d)))
 
 """
-    firstindex(collection) -> Integer
-    firstindex(collection, d) -> Integer
+    firstindex(collection)::Integer
+    firstindex(collection, d)::Integer
 
 Return the first index of `collection`. If `d` is given, return the first index of `collection` along dimension `d`.
 
@@ -3147,7 +3147,7 @@ end
 ## iteration utilities ##
 
 """
-    foreach(f, c...) -> Nothing
+    foreach(f, c...) -> nothing
 
 Call function `f` on each element of iterable `c`.
 For multiple iterable arguments, `f` is called elementwise, and iteration stops when

base/abstractarraymath.jl

@@ -9,7 +9,7 @@ isreal(x::AbstractArray{<:Real}) = true
 ## Constructors ##
 
 """
-    vec(a::AbstractArray) -> AbstractVector
+    vec(a::AbstractArray)::AbstractVector
 
 Reshape the array `a` as a one-dimensional column vector. Return `a` if it is
 already an `AbstractVector`. The resulting array

base/abstractset.jl

@@ -302,9 +302,9 @@ end
 const ⊆ = issubset
 function ⊇ end
 """
-    issubset(a, b) -> Bool
-    ⊆(a, b) -> Bool
-    ⊇(b, a) -> Bool
+    issubset(a, b)::Bool
+    ⊆(a, b)::Bool
+    ⊇(b, a)::Bool
 
 Determine whether every element of `a` is also in `b`, using [`in`](@ref).
 
@@ -394,8 +394,8 @@ used to implement specialized methods.
 function ⊊ end
 function ⊋ end
 """
-    ⊊(a, b) -> Bool
-    ⊋(b, a) -> Bool
+    ⊊(a, b)::Bool
+    ⊋(b, a)::Bool
 
 Determines if `a` is a subset of, but not equal to, `b`.
 
@@ -446,8 +446,8 @@ used to implement specialized methods.
 function ⊈ end
 function ⊉ end
 """
-    ⊈(a, b) -> Bool
-    ⊉(b, a) -> Bool
+    ⊈(a, b)::Bool
+    ⊉(b, a)::Bool
 
 Negation of `⊆` and `⊇`, i.e. checks that `a` is not a subset of `b`.
 
@@ -496,7 +496,7 @@ used to implement specialized methods.
 ## set equality comparison
 
 """
-    issetequal(a, b) -> Bool
+    issetequal(a, b)::Bool
 
 Determine whether `a` and `b` have the same elements. Equivalent
 to `a ⊆ b && b ⊆ a` but more efficient when possible.
@@ -544,7 +544,7 @@ issetequal(a) = Fix2(issetequal, a)
 
 ## set disjoint comparison
 """
-    isdisjoint(a, b) -> Bool
+    isdisjoint(a, b)::Bool
 
 Determine whether the collections `a` and `b` are disjoint.
 Equivalent to `isempty(a ∩ b)` but more efficient when possible.