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
• interpolation
• @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 of documented bindings.

Effectively, it replaces all the matching docstrings in the module with the template. The DOCSTRING abbreviation can be used to splice the original docstring into the replacement docstring generated from the template.

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.