Templates

@template CATEGORY = "template"
@template (CATEGORY, ...) = "template"
@template CATEGORY = Module

Defines a docstring template for a category, or a tuple of categories, of documented bindings in the current module.

Each matching docstring that follows the @template is replaced by the template, with the original docstring placed where the template's DOCSTRING abbreviation is. Every template must contain DOCSTRING. Docstrings defined before the @template are left as they are, so define templates before the definitions they should apply to. A template applies only in the module that defines it. Submodules need their own, or a copy as shown below. A docstring that contains NOTEMPLATE renders as written.

Examples

julia> module Geometry
       using DocStringExtensions
       @template (FUNCTIONS, METHODS) = """
           $(TYPEDSIGNATURES)
           $(DOCSTRING)
           """
       "Compute the area of a square."
       area(side::Int) = side^2
       end;

julia> @doc Geometry.area
  area(side::Int64) -> Int64

  Compute the area of a square.

The remaining examples show the other forms of @template.

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

DEFAULT applies to a docstring when no template for its own category, or for the category it falls back to, exists.

@template ABSTRACTTYPES =
    """
    $(TYPEDEF)
    $(DOCSTRING)
    $(SUBTYPES)
    """

ABSTRACTTYPES applies to abstract types, and TYPES to every other type. A module without an ABSTRACTTYPES template documents abstract types with its TYPES template.

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

A tuple of categories gives several categories the same template.

@template MODULES = ModName

A module name on the right copies that module's template for the same category. ModName must already define a MODULES template, so a module cannot copy a template from itself. To share templates across a package, define them in the parent module and copy them into each submodule:

module Parent
using DocStringExtensions
@template MODULES = """
    $(DOCSTRING)
    $(EXPORTS)
    """

module Child
using DocStringExtensions
@template MODULES = Parent
end
end

An Abbreviation that marks where a @template places the original docstring. Every template must contain it.

Examples

julia> module Shapes
       using DocStringExtensions
       @template (FUNCTIONS, METHODS) = """
           $(DOCSTRING)
           Part of the `Shapes` module.
           """
       "Compute the area of a square."
       area(side) = side^2
       end;

julia> @doc Shapes.area
  Compute the area of a square. Part of the Shapes module.

An Abbreviation that stops the module's @template applying to the docstring it appears in. It prints nothing.

Examples

julia> module Shapes
       using DocStringExtensions
       @template (FUNCTIONS, METHODS) = """
           $(TYPEDSIGNATURES)
           $(DOCSTRING)
           """
       """
       Compute the area of a square.
       $(NOTEMPLATE)
       """
       area(side::Int) = side^2
       end;

julia> @doc Shapes.area
  Compute the area of a square.

The abbreviation behind NOTEMPLATE. TemplateOverride(category) applies the module's @template for category to the docstring it appears in, in place of the template for the documented object's own category. category is one of the categories @template accepts, and the module must define a template for it before the docstring.