GitHub

Functions and methods

The docstrings for these abbreviations are in the reference.

"""
`foo` is declared with `function foo end`, so this docstring belongs to the function, not
to one method. [`METHODLIST`](@ref) lists its methods with links to their source:

$(METHODLIST)

---

[`TYPEDMETHODLIST`](@ref) lists the same methods with argument and return types:

$(TYPEDMETHODLIST)
"""
function foo end

"""
This method has a default value for `y`, so Julia defines two methods, `foo(x::Int)` and
`foo(x::Int, y::Int)`. [`SIGNATURES`](@ref) prints both:

$(SIGNATURES)

---

[`TYPEDSIGNATURES`](@ref) adds the argument types and the inferred return type:

$(TYPEDSIGNATURES)

---

Passing `defaults = true` to [`MethodSignatures`](@ref DocStringExtensions.MethodSignatures)
or [`TypedMethodSignatures`](@ref DocStringExtensions.TypedMethodSignatures) shows the
default value and prints the two methods as one signature:

$(DocStringExtensions.TypedMethodSignatures(defaults = true))

---

Passing `defaults = :brackets` prints one signature without the default value, with the
optional argument in brackets:

$(DocStringExtensions.MethodSignatures(defaults = :brackets))

---

Passing a string as `returns` describes the return value in place of the inferred type:

$(DocStringExtensions.MethodSignatures(returns = "sum::Int"))

---

[`FUNCTIONNAME`](@ref) prints the function's name, here $(FUNCTIONNAME), for use in a
signature written by hand:

    $(FUNCTIONNAME)(x, ...)
"""
foo(x::Int, y::Int=3) = x + y

"""
A second method of [`$(FUNCTIONNAME)`](@ref). [`SIGNATURES`](@ref):

$(SIGNATURES)

[`TYPEDSIGNATURES`](@ref) also prints the type of the keyword argument `pad`:

$(TYPEDSIGNATURES)

[`BODY`](@ref) prints the method's body:

$(BODY)
"""
foo(x::String; pad::Int = 0) = length(x) + pad

The docstrings render as:

Examples.foo — Method

This method has a default value for y, so Julia defines two methods, foo(x::Int) and foo(x::Int, y::Int). SIGNATURES prints both:

foo(x)
foo(x, y)

TYPEDSIGNATURES adds the argument types and the inferred return type:

foo(x::Int64) -> Int64
foo(x::Int64, y::Int64) -> Int64

Passing defaults = true to MethodSignatures or TypedMethodSignatures shows the default value and prints the two methods as one signature:

foo(x::Int64, y::Int64=3) -> Int64

Passing defaults = :brackets prints one signature without the default value, with the optional argument in brackets:

foo(x, [y])

Passing a string as returns describes the return value in place of the inferred type:

foo(x) -> sum::Int
foo(x, y) -> sum::Int

FUNCTIONNAME prints the function's name, here foo, for use in a signature written by hand:

foo(x, ...)
source

Type parameters

TYPEDSIGNATURES rebuilds a signature from Julia's internal representation, so type parameters may print differently from the source:

"""
A method for [`$(FUNCTIONNAME)`](@ref) with one type parameter. [`TYPEDSIGNATURES`](@ref):

$(TYPEDSIGNATURES)

For comparison, [`SIGNATURES`](@ref):

$(SIGNATURES)
"""
bar(x::AbstractArray{T}, y::T) where {T <: Integer} = Int(y)

"""
A method for [`$(FUNCTIONNAME)`](@ref) with an unnamed argument. [`TYPEDSIGNATURES`](@ref):

$(TYPEDSIGNATURES)

For comparison, [`SIGNATURES`](@ref):

$(SIGNATURES)
"""
bar(x::AbstractArray{T}, ::String) where {T <: Integer} = x

"""
A method for [`$(FUNCTIONNAME)`](@ref) with two type parameters. [`TYPEDSIGNATURES`](@ref):

$(TYPEDSIGNATURES)

For comparison, [`SIGNATURES`](@ref):

$(SIGNATURES)
"""
bar(x::AbstractArray{T}, y::U) where {T <: Integer, U <: AbstractFloat} = 0

The docstrings render as:

Macros

SIGNATURES and TYPEDSIGNATURES print a macro the way it is called, with its arguments separated by spaces:

"""
Repeat `ex` a number of times. [`SIGNATURES`](@ref) prints the macro as its caller writes
it, without the `__source__` and `__module__` arguments every macro receives:

$(SIGNATURES)

---

[`TYPEDSIGNATURES`](@ref) adds the argument types, and no return type:

$(TYPEDSIGNATURES)

---

Passing `defaults = true` shows the default value in one signature:

$(DocStringExtensions.MethodSignatures(defaults = true))
"""
macro repeat(ex::Expr, n = 2)
    return Expr(:block, fill(ex, n)...)
end

The docstring renders as:

Examples.@repeat — Macro

Repeat ex a number of times. SIGNATURES prints the macro as its caller writes it, without the __source__ and __module__ arguments every macro receives:

@repeat ex
@repeat ex n

TYPEDSIGNATURES adds the argument types, and no return type:

@repeat ex::Expr
@repeat ex::Expr n

Passing defaults = true shows the default value in one signature:

@repeat ex n=2
source

Function bodies

BODY prints the code of the documented method. Julia prints it from the parsed expression, so comments are dropped and some syntax is normalised, such as for x in xs printing as for x = xs:

"""
The values that appear more than once in `xs`. [`BODY`](@ref) prints the method's body,
with nested blocks and a macro call:

$(BODY)
"""
function duplicates(xs)
    counts = Dict{eltype(xs),Int}()
    for x in xs
        if haskey(counts, x)
            counts[x] += 1
        else
            @debug "first sighting" x
            counts[x] = 1
        end
    end
    return [k for (k, n) in counts if n > 1]
end

The docstring renders as:

Examples.duplicates — Function

The values that appear more than once in xs. BODY prints the method's body, with nested blocks and a macro call:

counts = Dict{eltype(xs), Int}()
for x = xs
    if haskey(counts, x)
        counts[x] += 1
    else
        @debug "first sighting" x
        counts[x] = 1
    end
end
return [k for (k, n) = counts if n > 1]
source