Explicit type annotation in document for function in julia

[hungpham3112]

AFAIK, julia is famous for its rich type system so I expected that Julia document is where I should rely on. Every time when searching the function with help mode I want to know what datatype I could get after I use one function, for example:

  sum(f, A::AbstractArray; dims)


  Sum the results of calling function f on each element of an array over the given dimensions.

  Examples
  ≡≡≡≡≡≡≡≡≡≡

  julia> A = [1 2; 3 4]
  2×2 Matrix{Int64}:
   1  2
   3  4

  julia> sum(abs2, A, dims=1)
  1×2 Matrix{Int64}:
   10  20

  julia> sum(abs2, A, dims=2)
  2×1 Matrix{Int64}:
    5
   25

My expected is something like this:

sum(f, A::AbstractArray; dims)::Number

or

sum(f, A::AbstractArray; dims) -> Number

The function sum is popular so it's not maybe good example for imagination, what about coalesce:

help?> coalesce
search: coalesce @coalesce

  coalesce(x...)


  Return the first value in the arguments which is not equal to missing, if any. Otherwise return missing.

  See also skipmissing, something, @coalesce.

  Examples
  ≡≡≡≡≡≡≡≡≡≡

  julia> coalesce(missing, 1)
  1

  julia> coalesce(1, missing)
  1

  julia> coalesce(nothing, 1)  # returns `nothing`

  julia> coalesce(missing, missing)
  missing

The function name: coalesce is ambiguous in the name for beginner. It will be better if something similar:
coalesce(x::Vector{Int64}...) -> Union{Int64, missing}
with this explicit annotation I know exactly what I'm doing. Is there any part of julia document as my expectation? Yes, map:

map(f, A::AbstractArray...) -> N-array


  When acting on multi-dimensional arrays of the same ndims, they must all have the same axes, and the answer will too.

  See also broadcast, which allows mismatched sizes.

  Examples
  ≡≡≡≡≡≡≡≡≡≡

  julia> map(//, [1 2; 3 4], [4 3; 2 1])
  2×2 Matrix{Rational{Int64}}:
   1//4  2//3
   3//2  4//1

  julia> map(+, [1 2; 3 4], zeros(2,1))
  ERROR: DimensionMismatch

  julia> map(+, [1 2; 3 4], [1,10,100,1000], zeros(3,1))  # iterates until 3rd is exhausted
  3-element Vector{Float64}:
     2.0
    13.0
   102.0

maybe N-array is not actually a type it could be MapArray but at least I know it return something so my thinking workflow input -> map() -> output1 -> coalesce -> result will be smooth btw.
To compare current julia state we can see our nearest neighborhood: Python. According to typing module in python where type annotation is encourage but not default option:

Type aliases

A type alias is defined by assigning the type to the alias. In this example, Vector and list[float] will be treated as interchangeable synonyms:

Vector = list[float]

def scale(scalar: float, vector: Vector) -> Vector:
    return [scalar * num for num in vector]

# passes type checking; a list of floats qualifies as a Vector.
new_vector = scale(2.0, [1.0, -4.2, 5.4])

or even more explicit like rust:

pub fn range<R>(range: R, bounds: RangeTo<usize>) -> Range<usize>
where
    R: RangeBounds<usize>,

After all of that, I'm not sure if it's only julia current state, in the future we could have better document and function in the core will have explicit type annotation so newcomers can understand code better. I know type annotation is only optional, you can write function with or without it but the changing in core function as a leader so the ecosystem will look at that and changing more. so we will have what actually strong type system in not only the implementation and documentation but also encourage people to write a better code.

My thought is personal so it maybe bias or limit, perhaps I'm missing insight about the julia core implementation or julia actually in the state where document doesn't good enough.