# Should we be documenting the type that a function returns?

**URL:** <https://discourse.julialang.org/t/should-we-be-documenting-the-type-that-a-function-returns/7125>\
**Category:** Community\
**Tags:** question, package, documentation\
**Created:** [November 17, 2017, 1:05pm UTC](https://discourse.julialang.org/t/should-we-be-documenting-the-type-that-a-function-returns/7125 "2017-11-17T13:05:53Z")\
**Posts on this page:** 6\
**Page:** 1

<div class="post-metadata">

**Author:** ![zygmuntszpak](https://sea2.discourse-cdn.com/julialang/user_avatar/discourse.julialang.org/zygmuntszpak/32/2591_2.png) [@zygmuntszpak](https://discourse.julialang.org/u/zygmuntszpak)\
**Post date:** [November 17, 2017, 1:05pm UTC](https://discourse.julialang.org/t/should-we-be-documenting-the-type-that-a-function-returns/7125/1 "2017-11-17T13:05:53Z")

</div>

I’ve been studying the Image.jl package and I’ve noticed that whilst the documentation for a function explains what each parameter does, the documentation in general does not comment on the data structure that the function returns.

For example, say I want to find the [corners in an image](https://github.com/JuliaImages/Images.jl/blob/master/src/corner.jl) , without actually looking at the source code of the function, I don’t know whether the corners will be a returned as a matrix of numbers, or a vector of special corner types, or a matrix of Boolean etc.

I’m wondering if this is idiomatic of Julia packages in general? Is there a particular reason why return types are not discussed, or is it just a convention adopted by that particular package (@tim.holy )?

---

<div class="post-metadata">

**Author:** ![Tamas\_Papp](https://sea2.discourse-cdn.com/julialang/user_avatar/discourse.julialang.org/tamas_papp/32/25949_2.png) [@Tamas\_Papp](https://discourse.julialang.org/u/Tamas_Papp)\
**Post date:** [November 17, 2017, 1:17pm UTC](https://discourse.julialang.org/t/should-we-be-documenting-the-type-that-a-function-returns/7125/2 "2017-11-17T13:17:18Z")

</div>

I can’t speak for other people, but I like to organize my code around _verbs_ (ie functions) instead of _nouns_ (values and their types). So if I call

```julia
y = foo(x)

```

it is more important for me to know that what `y` represents and what I can _do_ with it, eg

```julia
z = bar(y)

```

than how it is actually implemented. The former I can find out by

1. looking at the library docs,
2. using `methodswith` or similar.

For a well-designed library, the answers to these questions should be the same _even if the type of `y` is changed at some point_. If I am really curious about he latter, I can always do `?` on the type of `y`, `dump(y)`, etc. But I rarely feel I need to.

---

<div class="post-metadata">

**Author:** ![thofma](https://sea2.discourse-cdn.com/julialang/user_avatar/discourse.julialang.org/thofma/32/1691_2.png) [@thofma](https://discourse.julialang.org/u/thofma)\
**Post date:** [November 17, 2017, 1:26pm UTC](https://discourse.julialang.org/t/should-we-be-documenting-the-type-that-a-function-returns/7125/3 "2017-11-17T13:26:00Z")

</div>

There is no rule. I personally think that it is useful and so do the authors of Base (there is also some issue about the preferred syntax, but I cannot find it):

```julia
help?> length
search: length hooklength set_length! leglength pol_length

  length(A::AbstractArray) -> Integer

  Returns the number of elements in A.

```

---

<div class="post-metadata">

**Author:** ![fredrikekre](https://sea2.discourse-cdn.com/julialang/user_avatar/discourse.julialang.org/fredrikekre/32/1688_2.png) [@fredrikekre](https://discourse.julialang.org/u/fredrikekre)\
**Post date:** [November 17, 2017, 2:47pm UTC](https://discourse.julialang.org/t/should-we-be-documenting-the-type-that-a-function-returns/7125/4 "2017-11-17T14:47:51Z")

</div>

> [@thofma](#):
>
> there is also some issue about the preferred syntax, but I cannot find it

> <https://github.com/JuliaLang/julia/issues/22804>
>
> It looks like Base is using the following convention to document return types
> \`…\`\`julia
> """
> foo(x::Integer) -\> Integer
> """
> foo(x::Integer) = x
> \`\`\`
> 
> The proposal is to use Julia's return syntax instead, e.g.
> \`\`\`julia
> """
> foo(x::Integer)::Integer
> """
> foo(x::Integer) = x
> \`\`\`
> 
> related https://github.com/JuliaLang/julia/issues/4902

---

<div class="post-metadata">

**Author:** ![tim.holy](https://sea2.discourse-cdn.com/julialang/user_avatar/discourse.julialang.org/tim.holy/32/52_2.png) [@tim.holy](https://discourse.julialang.org/u/tim.holy)\
**Post date:** [November 17, 2017, 2:49pm UTC](https://discourse.julialang.org/t/should-we-be-documenting-the-type-that-a-function-returns/7125/5 "2017-11-17T14:49:01Z")

</div>

It’s interesting and deliciously ironic that you found that in the Images package, because I’ve [recently advocated a related viewpoint](https://github.com/JuliaLang/julia/pull/23939#discussion_r142804859). I agree that we should be informative about the outputs, and when you find otherwise it’s most likely a chance for improvement.

That said, I’d echo @Tamas_Papp’s point above. With regards to input to a function, usually I prefer to design my code so that it only requires certain “behavioral contracts,” but these contracts don’t always require a specific representation: they might work for a tuple, `Array`, or other kind of iterable container. I’m not sure the outputs should be treated differently.

---

<div class="post-metadata">

**Author:** ![jballanc](https://sea2.discourse-cdn.com/julialang/user_avatar/discourse.julialang.org/jballanc/32/328_2.png) [@jballanc](https://discourse.julialang.org/u/jballanc)\
**Post date:** [November 19, 2017, 4:57pm UTC](https://discourse.julialang.org/t/should-we-be-documenting-the-type-that-a-function-returns/7125/6 "2017-11-19T16:57:50Z")

</div>

> [@tim.holy](#):
>
> With regards to input to a function, usually I prefer to design my code so that it only requires certain “behavioral contracts,”

Certainly would be easier to do with some way of describing the return values as having a flavor of some sort…some sort of…trait? 😉

…ok, I’ll be quiet now.