JuliaDocs / JuliaDocs/DocStringExtensions.jl

Internal errors when (ab)using `@template`

Open
#151 1 comment 0 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

Dominant language
Julia
Stars
126
Forks
35
PR merge metrics
No merged PRs in 30d

Description

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

Contributor guide

No contributing guide indexed for this repository

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

Research direction

Reproduce the two examples in the issue, then inspect src/templates.jl and src/abbreviations.jl at the reported locations. Trace string-only templates and $SIGNATURES on function declarations, and add focused regression coverage if the repository provides a suitable test location. Done means both cases avoid internal MethodError failures and either work as requested or report a helpful error.

Written by the indexing model from the issue text.

Assessment

Tech stack
julia
Domain
documentation
Issue type
Bug
Difficulty
4/5
Estimated time
3-5 days
Activity status
Stale
Clarity
Mostly clear
Newbie friendliness
45/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.