# Explicit type annotation in document for function in julia · JuliaLang/julia
**URL:** https://discourse.julialang.org/t/explicit-type-annotation-in-document-for-function-in-julia-julialang-julia/102137
**Category:** General Usage
**Tags:** question, documentation, type
**Created:** [July 27, 2023, 1:07am UTC](https://discourse.julialang.org/t/explicit-type-annotation-in-document-for-function-in-julia-julialang-julia/102137 "2023-07-27T01:07:27Z")
**Posts on this page:** 7
**Page:** 1
### Author:  [@hungpham3112](https://discourse.julialang.org/u/hungpham3112)
#### Post date: [July 27, 2023, 1:07am UTC](https://discourse.julialang.org/t/explicit-type-annotation-in-document-for-function-in-julia-julialang-julia/102137/1 "2023-07-27T01:07:27Z")
> **[Explicit type annotation in document for function in julia · JuliaLang/julia...](https://github.com/JuliaLang/julia/discussions/50686)**
>
> 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 cou...
---
### Author:  [@Benny](https://discourse.julialang.org/u/Benny)
#### Post date: [July 27, 2023, 1:47am UTC](https://discourse.julialang.org/t/explicit-type-annotation-in-document-for-function-in-julia-julialang-julia/102137/2 "2023-07-27T01:47:45Z")
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.
---
### Author:  [@mrufsvold](https://discourse.julialang.org/u/mrufsvold)
#### Post date: [July 27, 2023, 1:56am UTC](https://discourse.julialang.org/t/explicit-type-annotation-in-document-for-function-in-julia-julialang-julia/102137/3 "2023-07-27T01:56:51Z")
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.
---
### Author:  [@hungpham3112](https://discourse.julialang.org/u/hungpham3112)
#### Post date: [July 27, 2023, 2:49am UTC](https://discourse.julialang.org/t/explicit-type-annotation-in-document-for-function-in-julia-julialang-julia/102137/4 "2023-07-27T02:49:18Z")
> [@Benny](#):
>
> 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
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
> [@Benny](#):
>
> `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.
Yeb, if I’m a beginner, I want the hint everywhere, not only for some like `isa, nameof...`
---
### Author:  [@hungpham3112](https://discourse.julialang.org/u/hungpham3112)
#### Post date: [July 27, 2023, 2:59am UTC](https://discourse.julialang.org/t/explicit-type-annotation-in-document-for-function-in-julia-julialang-julia/102137/5 "2023-07-27T02:59:18Z")
> 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
```julia
[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.
---
### Author:  [@Benny](https://discourse.julialang.org/u/Benny)
#### Post date: [July 27, 2023, 3:45am UTC](https://discourse.julialang.org/t/explicit-type-annotation-in-document-for-function-in-julia-julialang-julia/102137/6 "2023-07-27T03:45:05Z")
> [@hungpham3112](#):
>
> So, you are saying we can’t sure what we will have after using a function like sum right?
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.
---
### Author:  [@hungpham3112](https://discourse.julialang.org/u/hungpham3112)
#### Post date: [July 27, 2023, 2:50pm UTC](https://discourse.julialang.org/t/explicit-type-annotation-in-document-for-function-in-julia-julialang-julia/102137/7 "2023-07-27T14:50:49Z")
Thanks @Benny for your answer. I found a question on [stackoverflow](https://stackoverflow.com/questions/8059649/how-to-document-a-duck-type) 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](http://docs.python.org/library/random.html#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.