Replace -> with :: where appropriate in docstrings (JuliaLang#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:
JuliaLang#56978 (comment) and
applied throughout the repo.

As documented here JuliaLang#57583

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

Author: LilithHafner

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.

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.

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.
 """

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
 

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

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`.
 """