Functions and methods

An Abbreviation that prints the signatures of the documented method, with argument names and keywords but no types or default values. An unnamed argument prints as ::T when it declares a type T, and as _ otherwise. A destructured argument prints as written, such as (a, b).

In the docstring of a struct, it prints the constructors that the struct definition creates. A callable method of a type's instances, such as (e::E)(x), prints as it is defined. In the docstring of a macro, it prints the macro as its caller writes it, such as @m a b, without the __source__ and __module__ arguments.

Examples

julia> """
       $(SIGNATURES)
       Compute the area of a rectangle.
       """
       area(width, height = width) = width * height;

julia> @doc area
  area(width)
  area(width, height)

  Compute the area of a rectangle.

An Abbreviation that prints the signatures of the documented method like SIGNATURES, with the types of positional and keyword arguments and the inferred return type. Type parameters keep their names, declared in a where clause after the arguments, and default values are left out as in SIGNATURES. In the docstring of a struct, it prints the constructors that SIGNATURES lists. A callable such as (e::E)(x::Int) prints as (e::Main.E)(x::Int64) when E is defined in Main. Before Julia 1.6, a callable and a constructor written T{P}(...) print without a return type. A macro prints as SIGNATURES prints it, with argument types such as @m ex::Expr and no inferred return type. An inferred return type that Julia would print with a name it generated, as for a parameter written <:T that no const alias gives, is left out.

Examples

julia> """
       $(TYPEDSIGNATURES)
       Compute the area of a rectangle.
       """
       area(width::Int, height::Int) = width * height;

julia> @doc area
  area(width::Int64, height::Int64) -> Int64

  Compute the area of a rectangle.

An Abbreviation that prints the name of the documented function. Use it in a signature written by hand, for example on a function with no methods yet.

The name is printed as plain text. Indent it or wrap it in backticks to format it as code.

Examples

julia> """
       `$(FUNCTIONNAME)(d, θ)` calculates the log density of `d` at `θ`.
       """
       function logdensity end;

julia> @doc logdensity
  logdensity(d, θ) calculates the log density of d at θ.

An Abbreviation that prints the body of the documented method definition as a Julia code block. Short functions are sometimes best documented by their definition.

It prints nothing when the docstring is not attached to a method definition with a body.

Examples

julia> """
       Log-odds of the probability `p`:
       $(BODY)
       """
       logit(p) = log(p / (1 - p));

julia> @doc logit
  Log-odds of the probability p:

  log(p / (1 - p))

An Abbreviation that lists the methods of the documented function or type that are defined in the current module. Each method shows its signature and a link to the line that defines it.

Examples

Methods defined in the REPL have no file to link to, so the list below shows only their signatures.

julia> """
       Scale `x` by a factor.
       $(METHODLIST)
       """
       function scale end;

julia> scale(x) = 2x;

julia> scale(x, factor) = factor * x;

julia> @doc scale
  Scale x by a factor.

  scale(x, factor)
  scale(x)

An Abbreviation that lists methods like METHODLIST, with argument types and the inferred return type in each signature.

Examples

julia> """
       Scale `x` by a factor.
       $(TYPEDMETHODLIST)
       """
       function scale end;

julia> scale(x::Int) = 2x;

julia> scale(x::Float64, factor::Float64) = factor * x;

julia> @doc scale
  Scale x by a factor.

  scale(x::Float64, factor::Float64) -> Float64
  scale(x::Int64) -> Int64

MethodSignatures(; returns, defaults)

The abbreviation behind SIGNATURES. returns = true follows each signature with its inferred return type, and a string such as "success::Bool" prints in its place. defaults = true shows default values. defaults = :brackets marks each optional positional argument in brackets. By default returns = false and defaults = false, as in SIGNATURES.

TypedMethodSignatures(; returns, defaults)

The abbreviation behind TYPEDSIGNATURES. returns = false leaves out the return types, and a string such as "success::Bool" prints in their place. defaults takes the values that MethodSignatures takes. By default returns = true and defaults = false, as in TYPEDSIGNATURES.

MethodList(; returns)

The abbreviation behind METHODLIST. returns = true follows each signature with its inferred return type. By default returns = false, as in METHODLIST.

TypedMethodList(; returns)

The abbreviation behind TYPEDMETHODLIST. returns = false leaves out the return types. By default returns = true, as in TYPEDMETHODLIST.