Internals

Internals

These functions, types etc. are internal to DocStringExtensions and not part of the public API. They may change or be removed arbitrarily from version to version.

alltypesigs(sig)

Returns a Vector of the Tuple types contained in sig.

arguments(m)

Returns the list of arguments for a particular method m.

Examples

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

Remove the Pkg.dir part of a file path if it exists.

comparemethods(a, b)

Compare methods a and b by file and line number.

find_tuples(typesig)

Converts a method signature (or a union of several signatures) in a vector of (single) signatures.

This is used for decoding the method signature that a docstring is paired with. In the case when the docstring applies to multiple methods (e.g. when default positional argument values are used and define multiple methods at once), they are combined together as union of Tuple types.

julia> DocStringExtensions.find_tuples(Tuple{String,Number,Int})
1-element Array{DataType,1}:
 Tuple{String,Number,Int64}

julia> DocStringExtensions.find_tuples(Tuple{T} where T <: Integer)
1-element Array{DataType,1}:
 Tuple{T<:Integer}

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

julia> DocStringExtensions.find_tuples(s)
5-element Array{DataType,1}:
 Tuple{Int64}
 Tuple{U}
 Tuple{T}
 Tuple{Int64,T}
 Tuple{Int64,T,U}
format(abbr, buf, doc)

Expand the Abbreviation abbr in the context of the DocStr doc and write the resulting markdown-formatted text to the IOBuffer buf.

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 that 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
hook!(func)

Set the docstring expander function to first call func before calling the default expander.

To remove a hook that has been applied using this method call hook!().

hook!()

Reset the docstring expander to only call the default expander function. This clears any 'hook' that has been set using hook!(func).

isabstracttype(t)

Is the type t an abstract type?

isbitstype(t)

Is the type t a bitstype?

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)))
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::Base.GenericIOBuffer{Array{UInt8,1}}, binding::Base.Docs.Binding, func::Any, method::Method, typesig::Any) -> Base.GenericIOBuffer{Array{UInt8,1}}

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

  • no TypeVars;
  • no types;
  • no keyword default values;

Examples

f(x::Int; a = 1, b...) = x
sig = printmethod(Docs.Binding(Main, :f), f, first(methods(f)))
printmethod(buffer, binding, func, method)

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

  • no TypeVars;
  • no types;
  • no keyword default values;
  • _ printed where #unused# arguments are found.

Examples

f(x; a = 1, b...) = x
sig = printmethod(Docs.Binding(Main, :f), f, first(methods(f)))
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.

Abbreviation objects are used to automatically generate context-dependent markdown content within documentation strings. Objects of this type interpolated into docstrings will be expanded automatically before parsing the text to markdown.

The singleton type for DOCSTRING abbreviations.

The singleton type for FUNCTIONNAME abbreviations.

The singleton type for LICENSE abbreviations.

The singleton type for METHODLIST abbreviations.

The singleton type for SIGNATURES abbreviations.

The singleton type for EXPORTS abbreviations.

The singleton type for IMPORTS abbreviations.

The singleton type for README abbreviations.

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.

The singleton type for TYPEDEF abbreviations.

The type for FIELDS abbreviations.

  • types

The singleton type for TYPEDSIGNATURES abbreviations.