GitHub

Templates

The docstrings for @template and DOCSTRING are in the reference.

@template wraps every later docstring of a given kind in a module, so the abbreviations are written once. DOCSTRING marks where each original docstring goes.

  • A template applies only to docstrings that come after it, so define templates before the definitions that use them.
  • A template applies only in the module that defines it. A submodule needs its own, or a copy made with @template CATEGORY = ParentModule.
  • Abstract types use the ABSTRACTTYPES template, or the TYPES template when the module defines no ABSTRACTTYPES one.
module Geometry
using DocStringExtensions

"""
This docstring comes before the `@template` definitions below, so it renders as written.
"""
unit_circle() = Circle(1.0)

@template (FUNCTIONS, METHODS) = """
    $(TYPEDSIGNATURES)
    $(DOCSTRING)
    """

@template TYPES = """
    $(TYPEDEF)
    $(DOCSTRING)
    $(TYPEDFIELDS)
    """

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

"""
This docstring holds only this sentence. `Shape` is abstract, so the `ABSTRACTTYPES` template
adds its subtypes below it in place of fields.
"""
abstract type Shape end

"""
This docstring holds only this sentence. The template adds the definition above it and the
fields below it.
"""
struct Circle <: Shape
    "The distance from the centre to the edge."
    radius::Float64
end

"""
This docstring holds only this sentence. The template adds the signature above it.
"""
area(c::Circle) = π * c.radius^2

module Plain
using DocStringExtensions
import ..Geometry: Circle

"""
`Plain` is a submodule of `Geometry` but defines no template of its own, so this docstring
renders as written.
"""
perimeter(c::Circle) = 2π * c.radius
end

module Copied
using DocStringExtensions
import ..Geometry
import ..Geometry: Circle

@template (FUNCTIONS, METHODS) = Geometry

"""
`Copied` copies the function template from `Geometry`, so the signature is added here too.
"""
diameter(c::Circle) = 2 * c.radius
end

end

The docstrings render as:

Examples.Geometry.Shape — Type
abstract type Shape

This docstring holds only this sentence. Shape is abstract, so the ABSTRACTTYPES template adds its subtypes below it in place of fields.

source
Examples.Geometry.Circle — Type
struct Circle <: Examples.Geometry.Shape

This docstring holds only this sentence. The template adds the definition above it and the fields below it.

  • radius::Float64: The distance from the centre to the edge.
source
Examples.Geometry.area — Function
area(c::Examples.Geometry.Circle) -> Float64

This docstring holds only this sentence. The template adds the signature above it.

source