DocStringExtensions

DocStringExtensionsModule

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

Imports

  • Base
  • Core
source

Index

Reference

DocStringExtensions.EXPORTSConstant

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

Note

The names are sorted alphabetically and ignore leading @ characters so that macros are not sorted before other names.

Examples

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


  - [`bar`](@ref)
  - [`@baz`](@ref)
  - [`foo`](@ref)
source
DocStringExtensions.FIELDSConstant

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.
source
DocStringExtensions.FUNCTIONNAMEConstant

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
source
DocStringExtensions.IMPORTSConstant

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`
source
DocStringExtensions.METHODLISTConstant

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>).
source
DocStringExtensions.SIGNATURESConstant

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...)
```
source
DocStringExtensions.TYPEDEFConstant

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
```
Note

No information about the fields of the type is printed. Use the FIELDS abbreviation to include information about the fields of a type.

source
DocStringExtensions.TYPEDFIELDSConstant

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.
source
DocStringExtensions.TYPEDSIGNATURESConstant

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...)
```
source
DocStringExtensions.@templateMacro

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.

Note

Supported categories are DEFAULT, FUNCTIONS, METHODS, MACROS, TYPES, MODULES, and CONSTANTS.

source