Internals

alltypesigs(sig)

The Tuple types in sig, the signature a docstring is paired with. A docstring that documents several methods at once, such as those that positional default values define, is paired with the union of their signatures. Returns an empty vector for Union{}.

julia> DocStringExtensions.alltypesigs(Tuple{String,Number,Int})
1-element Vector{Any}:
 Tuple{String, Number, Int64}

julia> DocStringExtensions.alltypesigs(Tuple{T} where T <: Integer)
1-element Vector{Any}:
 Tuple{T} where T<:Integer

julia> s = Union{
         Tuple{Int64},
         Tuple{U},
         Tuple{T},
         Tuple{Int64,T},
         Tuple{Int64,T,U}
       } where U where T;

julia> DocStringExtensions.alltypesigs(s)
5-element Vector{Any}:
 Tuple{Int64}
 Tuple{U} where U
 Tuple{T} where T
 Tuple{Int64, T} where T
 Tuple{Int64, T, U} where {T, U}

append_defaults(
    args,
    kws,
    kwnames,
    method,
    definition;
    brackets
)

Append =default to each formatted argument in args and keyword in kws that has a default value in definition. kwnames names the keyword formatted in each entry of kws. With brackets set, wrap each positional argument that has a default in brackets and leave kws unchanged. Leaves both unchanged when method does not match definition.

argument_names(method, definition)

The positional argument names of method, with each destructured argument written as it appears in definition.

argument_types(method, n)

The declared types of the first n positional arguments of method, with a vararg argument's element type in place of its Vararg. A vararg with a count, such as xs::Vararg{Int,2}, gets Any.

arguments(m)

The names of the positional arguments of method m, with "_" for an unnamed or destructured argument.

Examples

f(x; a = 1, b...) = x
args = arguments(first(methods(f)))

callable_methods(func, typesig)

The methods of the instances of the type func whose arguments match typesig. These are the callables written as (e::T)(...), which methods(T) leaves out.

cleanpath(path)

Remove the depot prefix from a file path inside a depot, such as an installed package.

collapse_defaults(group, ::Nothing)

Drop the methods of group that Julia generated for positional default values, keeping the method that takes every argument of definition.

comparemethods(a, b)

Compare methods a and b by file and line number.

constructor_methods(func, typesig)

The methods of Type{T}, for T any instance of the parametric type func, whose arguments match typesig. These are the constructors written as T{P}(...). Julia stores D{T}(g) for struct D{T,MM} under Type{D{T}}, with MM free inside the invariant Type, so each leading run of func's parameters is searched.

constructor_parameters(func, method)

The type parameters written in a constructor call, such as [T] for Point{T}(x) where {T}, or nothing when method is not a constructor of func written with parameters. Julia stores such a method under Type{Point{T}}, so methods(Point) leaves it out.

definition_arguments(expr, show_defaults)

Find the arguments of the method definition expr, with their default values when show_defaults is set. Returns nothing when expr does not define a method, or when the arguments would not change what a signature prints.

definition_body(expr)

Render the body of the method definition expr as source text, one statement per line. Returns nothing when expr does not define a method or the body is empty.

documented_groups(groups, doc)

The group in groups that the docstring doc documents: the first defined at or after the docstring in its file. The docsystem adds a Tuple{T} to the type signature for each where T, which can match a method of another definition. All of groups when doc records no location or no group follows it.

expanded_vararg(method)

Whether method takes xs::Vararg{T,n}, which Julia writes into method.sig as n arguments of type T.

field_defaults(expr)

Find the default value of each field of the struct definition expr, rendered as source text and keyed by field name. Defaults are written as field = value inside a macro such as Base.@kwdef. Returns nothing when expr does not define a struct or no field has a default.

getmethods!(results, f, sig)

A helper method for getmethods that collects methods in results.

getmethods(f, sig)

Collect and return all methods of function f matching signature sig.

This is similar to methods(f, sig), but handles type signatures found in DocStr objects more consistently than methods.

groupby!(f, groups, data)

A helper method for groupby that uses a pre-allocated groups Dict.

groupby(f, K, V, data)

Group data using function f where key type is specified by K and group type by V.

The function f takes a single argument, an element of data, and should return a 2-tuple of (computed_key, element). See the example below for details.

Examples

groupby(Int, Vector{Int}, collect(1:10)) do num
    mod(num, 3), num
end

keyword_body(method)

The method holding the body of method, a method with keyword arguments, or nothing when it cannot be found. Julia lowers f(x; a::Int = 1) to a method of f that fills in the keyword defaults and ends by calling a hidden body method, #f#1(a::Int, ::typeof(f), x).

keyword_types(method, kws, vars)

The declared type of each keyword in kws, the keyword names of method, and the type parameters that only keyword types use. A keyword type refers to the parameter in vars of the same name, so it shares the signature's where clause.

keywords(func, m)

Returns the list of keywords for a particular method m of a function func.

Examples

f(x; a = 1, b...) = x
kws = keywords(f, first(methods(f)))

matched_methods(tt)

The methods matching the full call signature tt, a Tuple type of the callable's type and the argument types.

matches_definition(::Method, ::Nothing)

Whether method takes the positional arguments of definition, or a leading subset of them.

method_return_type(func, method, typesig)

The inferred return type of method for argument types typesig, as a vector holding one type, or an empty vector when method does not match typesig. Base.return_types infers every method that matches, so a more specific method whose signature overlaps method is skipped by its position in methods(func, typesig).

methodgroups(func, typesig, modname; exact)

Group all methods of function func with type signatures typesig in module modname. Keyword argument exact = true matches signatures "exactly" with == rather than <:.

Examples

groups = methodgroups(f, Union{Tuple{Any}, Tuple{Any, Integer}}, Main; exact = false)

parsedocs(mod)

Parse all docstrings defined within a module mod.

printmethod(
    buffer::IOBuffer,
    binding::Base.Docs.Binding,
    func,
    method::Method,
    typesig;
    returns,
    definition,
    brackets
) -> IOBuffer

Print a method signature to buffer with the argument types from typesig and the declared types of the keyword arguments, followed by the return annotation that returns selects (see return_annotation). Type parameters keep their names and are declared in a where clause after the arguments. Default values are left out unless definition gives them.

definition is as for the untyped printmethod.

Examples

julia> f(x::Int; a = 1, b...) = x;

julia> buffer = IOBuffer();

julia> DocStringExtensions.printmethod(buffer, Docs.Binding(@__MODULE__, :f), f, first(methods(f)), Tuple{Int});

julia> String(take!(buffer))
"f(x::Int64; a, b...) -> Int64"

printmethod(
    buffer,
    binding,
    func,
    method;
    definition,
    returns,
    brackets
)

Print a simplified representation of a method signature to buffer. Some of these simplifications include:

• no TypeVars, except those of a callable on Type{T}, such as (::Type{T})(x) where T<:Number;
• no types, except ::T for an unnamed argument of type T;
• no default values, unless definition gives them;
• _ printed for untyped unnamed arguments, and for destructured arguments unless definition gives them;
• a macro printed as its caller writes it, @m a b, without __source__ and __module__ or an inferred return type.

definition is the DefinitionArguments of the documented method definition, or nothing. returns selects the return_annotation after the signature.

Examples

julia> f(x; a = 1, b...) = x;

julia> buffer = IOBuffer();

julia> DocStringExtensions.printmethod(buffer, Docs.Binding(@__MODULE__, :f), f, first(methods(f)));

julia> String(take!(buffer))
"f(x; a, b...)"

return_annotation(returns, func, method, typesig)

The -> T that follows a signature, with the return_arrow. returns is true for the type that method is inferred to return for typesig, false for none, or the text to print as T. An inferred type that still shows a name Julia generated for a type variable is left out.

return_arrow()

The arrow between a signature and its return type: the value of DOCSTRINGEXTENSIONS_RETURN_ARROW, such as →, or -> when it is unset or empty.

signature_width()

The longest signature, in characters, that prints on one line: the value of DOCSTRINGEXTENSIONS_SIGNATURE_WIDTH, or 60 when it is unset or empty. A longer signature prints one argument per line. A value that is not a positive integer warns and gives 60.

signatures_equal(group, typesig)

Whether the methods of group together have the signature typesig. Subtyping cannot prove that for a vararg tuple split across methods, such as Tuple{Vararg{T}} where T and the two methods of f(x::T = 1, xs::T...) where {T}. So the types are compared at each number of arguments, up to one past the most parameters any tuple declares. Larger counts only meet varargs and compare the same.

sourcepath(file, mod)

The path of file relative to the root of the package that defines module mod, with / separators. Falls back to cleanpath when mod is not part of a package or file is outside it.

struct_constructors(func, definition, modname)

The constructors of the type func that its struct definition creates, from the module modname. In the definition's file, these are the methods defined no later than its last line; a constructor cannot exist before its type. When a macro wraps the definition, they include any constructor the macro may generate in another file.

struct_extent(expr)

The StructDefinition of the struct that expr defines, or nothing when expr does not define a struct or carries no line numbers.

url(m)

Get the URL (file and line number) where a method m is defined.

Note that this is based on the implementation of Base.url, but handles URLs correctly on TravisCI as well.

vararg_length(t)

The n of a Vararg{T,n} type, an Int or a method's type parameter, or nothing when the vararg has no count.

The positional and keyword arguments of a documented method definition, rendered as source text.

positional has a (name, default) entry for each positional argument, in order. name is the argument's name, the destructuring of a destructured argument such as "(a, b)", or "_" for an unnamed argument. default is nothing when the argument has no default. keywords maps the name of each keyword argument with a default to that default.

The singleton type for DOCSTRING abbreviations.

The singleton type for INSTANCES abbreviations.

The type for BODY abbreviations.

• body

The singleton type for FUNCTIONNAME abbreviations.

The singleton type for LICENSE abbreviations.

The singleton type for EXPORTS abbreviations.

The singleton type for IMPORTS abbreviations.

The singleton type for PUBLIC abbreviations.

The singleton type for README abbreviations.

Where a documented struct definition ends, which bounds the constructors that its signatures list.

• file: The file the definition is written in.

• last_line: The last line of the definition's body.

• wrapped: Whether a macro wraps the definition, and so may define constructors outside its body.

Internal abbreviation type used to wrap templated docstrings.

Location is a Symbol, either :before or :after. dict stores a reference to a module's templates. expr is the documented expression, which is passed to interpolation for each part of the template.

The singleton type for TYPEDEF abbreviations.

The singleton type for SUBTYPES abbreviations.