GitHub

Documentation

TanayLabUtilities.Documentation — Module

Enhanced documentation for functions. This allows using the default values of function parameters as the basis for default values of other function parameters.

TanayLabUtilities.Documentation.@documented — Macro 
@documented function something(...)
    return ...
end

Enhance the documentation of a function. This stashes the default value of named arguments. This allows expanding DEFAULT in the documentation string, which is especially useful if these defaults are computed, read from global constants, copied from other functions via function_default , etc. 

"Foo, default x: $(DEFAULT.x), default y: $(DEFAULT.y)."
@documented function foo(x::Integer = 1; y::Integer = 2)::Integer
    return x + y
end

@assert foo() == 3
@assert foo(2) == 4
println(repr("text/markdown", @doc foo))

# output

Foo, default x: `1`, default y: `2`.


"Foo, default x: $(DEFAULT.x)."
@documented function foo()::Integer
    return 1
end

println(repr("text/markdown", @doc foo))

# output

ERROR: no parameter (with default): x
exists for the function: foo


"Foo, default x: $(DEFAULT.x), default y: $(DEFAULT.y)."
function foo(x::Integer = 1; y::Integer = 2)::Integer
    return x + y
end

println(repr("text/markdown", @doc foo))

# output

ERROR: not a @documented function: foo
TanayLabUtilities.Documentation.DEFAULT — Constant

When using @documented , then $(DEFAULT.x) will be expanded with the default value of the parameter x . It is good practice to contain a description of the effects of each parameter somewhere in the documentation, and it is polite to also provide its default value. This can be done in either the signature line or in the text, or both. Using DEFAULT ensures that the correct value is used in the documentation.

TanayLabUtilities.Documentation.function_default — Function 
function_default(func::Function, parameter::Symbol)::Contract

Access the default of a parameter of a function annotated by @documented . 

@documented function foo(x::Integer = 1)::Nothing
    return nothing
end

println(function_default(foo, :x))
println(function_default(foo, :y))

# output

1
ERROR: no parameter (with default): y
exists for the function: foo


function foo(x::Integer = 1)::Nothing
    return nothing
end

function_default(foo, :x)

# output

ERROR: not a @documented function: foo

Index