DocStringExtensions

Extensions for the Julia docsystem.

Introduction

This package provides a collection of useful extensions for Julia's built-in docsystem. These are features that are still regarded as "experimental" and not yet mature enough to be considered for inclusion in Base, or that have sufficiently niche use cases that including them with the default Julia installation is not seen as valuable enough at this time.

Currently DocStringExtensions.jl exports a collection of so-called "abbreviations", which can be used to add useful automatically generated information to docstrings. These include information such as:

• simplified method signatures;
• documentation for the individual fields of composite types;
• import and export lists for modules;
• and source-linked lists of methods applicable to a particular docstring.

Users are most welcome to suggest additional abbreviation ideas, or implement and submit them themselves. Julia's strong support for program introspection makes this a reasonably straight forward process.

Details of the currently available abbreviations can be viewed in their individual docstrings listed below in the "Exports" section.

Examples

In simple terms an abbreviation can be used by simply interpolating it into a suitable docstring. For example:

using DocStringExtensions

"""
A short summary of `func`...

$(SIGNATURES)

where `x` and `y` should both be positive.

# Details

Some details about `func`...
"""
func(x, y) = x + y

$(SIGNATURES) will be replaced in the above docstring with

# Signatures

```julia
func(x, y)
```

The resulting generated content can be viewed via Julia's ? mode or, if Documenter.jl is set up, the generated external documentation.

The advantage of using SIGNATURES (and other abbreviations) is that docstrings are less likely to become out-of-sync with the surrounding code. Note though that references to the argument names x and y that have been manually embedded within the docstring are, of course, not updated automatically.

Exports

• DOCSTRING
• EXPORTS
• FIELDS
• FUNCTIONNAME
• IMPORTS
• LICENSE
• METHODLIST
• README
• SIGNATURES
• TYPEDEF
• TYPEDFIELDS
• TYPEDSIGNATURES
• @template

Imports

• Base
• Core

An Abbreviation used in @template definitions to represent the location of the docstring body that should be spliced into a template.

An Abbreviation to include all the exported names of a module is a sorted list of Documenter.jl-style @ref links.

Examples

The markdown text generated by the EXPORTS abbreviation looks similar to the following:

  - [`bar`](@ref)
  - [`@baz`](@ref)
  - [`foo`](@ref)

An Abbreviation to include the names of the fields of a type as well as any documentation that may be attached to the fields.

Examples

The generated markdown text should look similar to to following example where a type has three fields (x, y, and z) and the last two have documentation attached.

  - `x`

  - `y`

    Unlike the `x` field this field has been documented.

  - `z`

    Another documented field.

An Abbreviation for including the function name matching the method of the docstring.

Usage

This is mostly useful for not repeating the function name in docstrings where the user wants to retain full control of the argument list, or the latter does not exist (eg generic functions).

Note that the generated docstring snippet is not quoted, use indentation or explicit quoting.

Example

"""
    $(FUNCTIONNAME)(d, θ)

Calculate the logdensity `d` at `θ`.

Users should define their own methods for `FUNCTIONNAME`.
"""
function logdensity end

An Abbreviation to include all the imported modules in a sorted list.

Examples

The markdown text generated by the IMPORTS abbreviation looks similar to the following:

  - `Foo`
  - `Bar`
  - `Baz`

LICENSE

An Abbreviation for including the package LICENSE.md.

An Abbreviation for including a list of all the methods that match a documented Method, Function, or DataType within the current module.

Examples

The generated markdown text will look similar to the following example where a function f defines two different methods (one that takes a number, and the other a string):

```julia
f(num)
```

defined at [`<path>:<line>`](<github-url>).

```julia
f(str)
```

defined at [`<path>:<line>`](<github-url>).

README

An Abbreviation for including the package README.md.

An Abbreviation for including a simplified representation of all the method signatures that match the given docstring. See printmethod for details on the simplifications that are applied.

Examples

The generated markdown text will look similar to the following example where a function f defines method taking two positional arguments, x and y, and two keywords, a and the b.

```julia
f(x, y; a, b...)
```

An Abbreviation for including a summary of the signature of a type definition. Some of the following information may be included in the output:

• whether the object is an abstract type or a bitstype;
• mutability (either type or struct is printed);
• the unqualified name of the type;
• any type parameters;
• the supertype of the type if it is not Any.

Examples

The generated output for a type definition such as:

"""
$(TYPEDEF)
"""
struct MyType{S, T <: Integer} <: AbstractArray
    # ...
end

will look similar to the following:

```julia
struct MyType{S, T<:Integer} <: AbstractArray
```

Identical to FIELDS except that it includes the field types.

Examples

The generated markdown text should look similar to to following example where a type has three fields; x of type String, y of type Int, and z of type Vector{Any}.

  - `x::String`

  - `y::Int`

    Unlike the `x` field this field has been documented.

  - `z::Array{Any, 1}`

    Another documented field.

An Abbreviation for including a simplified representation of all the method signatures with types that match the given docstring. See printmethod for details on the simplifications that are applied.

Examples

The generated markdown text will look similar to the following example where a function f defines method taking two positional arguments, x and y, and two keywords, a and the b.

```julia
f(x::Int, y::Int; a, b...)
```

Defines a docstring template that will be applied to all docstrings in a module that match the specified category or tuple of categories.

Examples

@template DEFAULT =
    """
    $(SIGNATURES)
    $(DOCSTRING)
    """

DEFAULT is the default template that is applied to a docstring if no other template definitions match the documented expression. The DOCSTRING abbreviation is used to mark the location in the template where the actual docstring body will be spliced into each docstring.

@template (FUNCTIONS, METHODS, MACROS) =
    """
    $(SIGNATURES)
    $(DOCSTRING)
    $(METHODLIST)
    """

A tuple of categories can be specified when a docstring template should be used for several different categories.

@template MODULES = ModName

The template definition above will define a template for module docstrings based on the template for modules found in module ModName.

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.

format(abbr, buf, doc)

Expand the Abbreviationabbr in the context of the DocStrdoc and write the resulting markdown-formatted text to the IOBufferbuf.

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 groupsDict.

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;
• ? printed where #unused# arguments are found.

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.

The singleton type for TYPEDEF abbreviations.

The type for FIELDS abbreviations.

• types

The singleton type for TYPEDSIGNATURES abbreviations.