Docstring: how to format returns

General Usage
1

Hi,
I wonder if there is any standardized way of reporting function return in its docstring for something like this:

"""
    test(x)

Test whether `x` is greater than 0.

# Arguments

- `x::Int64`: the number to test

# Returns

- `::Bool`: true, if `x` is greater than zero
"""
function test(x::Int64)
    return x > 0
end

Since the function returns result and not a variable value, how should the returns look like?
- `::Bool`: true, if `x` is greater than zero
or
- `Bool`: true, if `x` is greater than zero
or
- `test::Bool`: true, if `x` is greater than zero - this seems to make most sense to me
?
Adam

2

This way:

"""
    test(x) -> Bool

Test whether `x` is greater than 0.
"""
test(x) = ...

is quite common, at least in Julia base documentation.

2 Likes
3

Thanks!

4

I’ve been thinking about this solution. It’s simple and elegant, but what about functions returning more complex outputs, e.g. a named tuple:

function test(x::Vector{Int})
    return (x1=x[1], x2=x[2])
end