Internal errors when (ab)using `@template`

[mortenpi]

I was trying to better understand what the @template macro does, and ran into some internal errors when I was trying out some (admittedly, perhaps silly) cases. I don't think these are very critical, but wanted to write them down somewhere.

• [ ] It looks like you can't have a string-only template. Could we support string-only templates or, alternatively, print a helpful error (e.g. that you should minimally have $DOCSTRING or something in the template)?

julia> module Foo
       using DocStringExtensions
       @template DEFAULT = "test"
       """
       function
       """
       function foo end
       function bar end
       end
ERROR: LoadError: MethodError: no method matching template(::LineNumberNode, ::Module, ::Symbol, ::String)

Closest candidates are:
  template(::LineNumberNode, ::Module, ::Symbol, ::Union{Expr, Symbol})
   @ DocStringExtensions ~/.julia/packages/DocStringExtensions/JVu77/src/templates.jl:92
  template(::LineNumberNode, ::Module, ::Expr)
   @ DocStringExtensions ~/.julia/packages/DocStringExtensions/JVu77/src/templates.jl:73
  template(::LineNumberNode, ::Module, ::Expr, ::Union{Expr, Symbol})
   @ DocStringExtensions ~/.julia/packages/DocStringExtensions/JVu77/src/templates.jl:78

Stacktrace:
 [1] template(src::LineNumberNode, mod::Module, ex::Expr)
   @ DocStringExtensions ~/.julia/packages/DocStringExtensions/JVu77/src/templates.jl:75
 [2] var"@template"(__source__::LineNumberNode, __module__::Module, ex::Any)
   @ DocStringExtensions ~/.julia/packages/DocStringExtensions/JVu77/src/templates.jl:68
in expression starting at REPL[4]:3

• [ ] Using $SIGNATURES in a template applied to function declaration leads to an error when accessing the docstrings. It is fine to use $SIGNATURES in a docstring of function foo end directly (it just doesn't interpolate anything into the docstring), so this error seems a bit inconsistent with that.

julia> module Foo
       using DocStringExtensions
       @template DEFAULT = "test $(SIGNATURES)"
       """
       function
       """
       function foo end
       function bar end
       end
WARNING: replacing module Foo.
Main.Foo

help?> Foo.foo
ERROR: MethodError: (::DocStringExtensions.var"#build_range#30"{Vector{Any}})(::DocStringExtensions.Template{:before}, ::Nothing) is ambiguous.

Candidates:
  (::DocStringExtensions.var"#build_range#30")(::DocStringExtensions.Template, ::Nothing)
    @ DocStringExtensions ~/.julia/packages/DocStringExtensions/JVu77/src/abbreviations.jl:649
  (::DocStringExtensions.var"#build_range#30")(::DocStringExtensions.Template{:before}, index)
    @ DocStringExtensions ~/.julia/packages/DocStringExtensions/JVu77/src/abbreviations.jl:650

Possible fix, define
  (::DocStringExtensions.var"#build_range#30")(::DocStringExtensions.Template{:before}, ::Nothing)

Stacktrace:
  [1] included_range(abbr::DocStringExtensions.Template{:before}, parts::Vector{Any})
    @ DocStringExtensions ~/.julia/packages/DocStringExtensions/JVu77/src/abbreviations.jl:656
  [2] format(abbr::DocStringExtensions.Template{:before}, buf::IOBuffer, doc::Base.Docs.DocStr)
    @ DocStringExtensions ~/.julia/packages/DocStringExtensions/JVu77/src/abbreviations.jl:639
  [3] formatdoc(buf::IOBuffer, doc::Base.Docs.DocStr, part::DocStringExtensions.Template{:before})
    @ DocStringExtensions ~/.julia/packages/DocStringExtensions/JVu77/src/abbreviations.jl:25
  [4] formatdoc(d::Base.Docs.DocStr)
    @ REPL ~/.julia/juliaup/julia-1.9.0+0.x64.linux.gnu/share/julia/stdlib/v1.9/REPL/src/docview.jl:88
  [5] parsedoc(d::Base.Docs.DocStr)
    @ REPL ~/.julia/juliaup/julia-1.9.0+0.x64.linux.gnu/share/julia/stdlib/v1.9/REPL/src/docview.jl:96
  [6] map!(f::typeof(Base.Docs.parsedoc), dest::Vector{Any}, A::Vector{Base.Docs.DocStr})
    @ Base ./abstractarray.jl:3254
  [7] mapany(f::Function, A::Vector{Base.Docs.DocStr})
    @ Base ./abstractarray.jl:3263
  [8] doc(binding::Base.Docs.Binding, sig::Type)
    @ REPL ~/.julia/juliaup/julia-1.9.0+0.x64.linux.gnu/share/julia/stdlib/v1.9/REPL/src/docview.jl:193
  [9] doc(binding::Base.Docs.Binding)
    @ REPL ~/.julia/juliaup/julia-1.9.0+0.x64.linux.gnu/share/julia/stdlib/v1.9/REPL/src/docview.jl:160
 [10] top-level scope
    @ ~/.julia/juliaup/julia-1.9.0+0.x64.linux.gnu/share/julia/stdlib/v1.9/REPL/src/docview.jl:553

[MichaelHatherly]

It looks like you can't have a string-only template. Could we support string-only templates or, alternatively, print a helpful error (e.g. that you should minimally have $DOCSTRING or something in the template)?

Yeah, supporting just plain strings could be done.

Using $SIGNATURES in a template applied to function declaration leads to an error when accessing the docstrings. It is fine to use $SIGNATURES in a docstring of function foo end directly (it just doesn't interpolate anything into the docstring), so this error seems a bit inconsistent with that.

Yeah, that shouldn't error. That'll need some debugging.