You’re giving examples of methods where it is misleading to document any return type or type hint: sum doesn’t always return a Number, it really depends on what f does; coalesce can return just about anything you put in it. The docstrings are also listing method signatures, not call signatures, so documenting coalesce(x::Vector{Int64}...) would be misleading because there’s no such method. It seems like when it is accurate to document a return type, it happens e.g. isa, nameof, summarysize.
map is documented with -> collection and -> N-array, and as you’ve said, those are not even types, just hints. The text of the docstring explain those hints adequately in my opinion, and it would be a mistake to try to cram that information into a type hint system.
Just to add to what Benny said, in Python, typing is a hint. In Julia, it is information for the compiler to use in dispatch and optimization. If this was a statically typed language, then the typing would also provide exact documentation for the human, but since this is a dynamic language, there is a near infinite combination of input and output types for any specific method.
I know it’s not a type so I said “something like this”.
It seems like when it is accurate to document a return type, it happens e.g.isa, nameof, summarysize.
This is exactly what I expected. Going deeper to understand Julia better, I find it’s probably because Julia has borrowed a lot of design from other languages and the current state is not where Julia shines with documentation. The documentation is fragmented and not inconsistent. IMHO
Yeb, if I’m a beginner, I want the hint everywhere, not only for some like isa, nameof...
If this was a statically typed language, then the typing would also provide exact documentation for the human, but since this is a dynamic language, there is a near infinite combination of input and output types for any specific method.
So, you are saying we can’t sure what we will have after using a function like sum right? I mean we can only imply in our head that
[1, 2, 3, 4] -> output will be an Int
[1, 2, 3.1, 4] -> output will be an Float
by practicing and learning the implicity underlying without knowing actual type at the time we see function. I’m not talking about how compiler define type at runtime, I want to know how can I get information about input(type) and output(type) at the time I see documentation.
You generally can’t look at a function or any one of its methods and determine what the output is; any output properties at this level are designed and documented as standards for extensions to follow. That’s different from a function call, where the inputs’ concrete types are often specific enough to compile and infer a return type, though there are exceptions. A function can have many methods, a method can be compiled for many function call signatures. If you want to document what a function call signature will return, you could, but there’s generally too many (with no finite limit) per method to document exhaustively, so only a few examples are shown.
Thanks @Benny for your answer. I found a question on stackoverflow about dynamic typing or duck typing that scratch my itches.
Also, for the most part, the standard library tries to avoid naming the specific methods demanded of a duck type. That leaves the implementation open to change. The random.sample API, for example, could have been defined in terms of iterables or in terms of sequences.
So, digging into this problem I found more insight about documentation and annotation thing. Because Julia decided to choose duck typing so this is a trade-off.