Why is it Convention to Repeat Function Signatures in Docstrings

General Usage
8

Sometimes the implementation contains a lot of cruft that’s not relevant to the caller, while the docstring’s signature can be written in a more user-friendly way that focuses on how the function/method is called, rather than how it’s implemented. Something like this:

"""
    diffetruct([T,] f, x, args...)

Perform diffetruction...
"""
function diffetruct end

function diffetruct(f, x, args...)
    # simple interface selecting default T
    return diffetruct(default_type(f, x), f, x, args...)
end

@inline function diffetruct(
    ::Type{T}, f::F, x::Integer, args::Vararg{Any,M}
) where {T,F,M}
    # expert interface with custom T
    # extra type parameters to force specialization on type,
    # function, and varargs
    # implementation specific to x::Integer
    [...]
end

@inline function diffetruct(
    ::Type{T}, f::F, x::AbstractFloat, args::Vararg{Any,M}
) where {T,F,M}
    # as above
    # implementation specific to x::AbstractFloat
    [...]
end
3 Likes