@template broken with Base.@__doc__?

[rafaqz]

@template doesn't seem to work when a struct is processed by a macro, and Base.@__doc__ is used in the macro.

The docs otherwise work fine. But the template is not inserted, although the format method does actually run.

[mortenpi]

Do you have a code snippet of what you mean by any chance?

[rafaqz]

Ok a simple example that doesn't actually need the @__doc__ macro but illustrates the problem:

module DocsCheck

using DocStringExtensions

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


macro documentbreaker(ex)
    :(Base.@__doc__ $(esc(ex)))
end

"Docs don't show typedef"
@documentbreaker struct BrokenDocs <: AbstractString 
    s::String
end


"Docs show typedef ^"
struct WorkingDocs <: AbstractString 
    s::String
end

end

Then:

help?> DocsCheck.WorkingDocs
  struct WorkingDocs <: AbstractString

  Docs show typedef ^

help?> DocsCheck.BrokenDocs
  Docs don't show typedef

julia> 

[marius311]

I think this is a simpler example:

julia> module Foo

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

       @doc raw"""
       stuff
       """
       foo() = 1
       end
Main.Foo

help?> Main.Foo.foo
  stuff

I was expecting the docstring at the end to have the signature added. This is DocStringExtensions v0.7.0 and Julia 1.1.0.

More generally, I need raw"..." or doc"..." docstrings since I tend to use lots of Latex. I don't currently see any way to make that work with this package due to this bug, but maybe there's a way I'm missing?

[bzinberg]

@marius311, I think I may have found a workaround:

"""$(raw"""
stuff
""")"""
foo() = 1

My rough understanding of why this works is that the relevant DocStrExtensions code path (namely, a call to DocStrExtensions.format) is used only when the docstring shows up as a :string node in the AST (e.g. (string "x = " x), not a bare literal like "a").

I am combining this with a different workaround, to get Documenter.jl to use the right "view source" link when combined with Base.@kwdef (rather than linking to the source of whatever name happens to first appear in the expansion of @kwdef):

@doc """Fields:
$(FIELDS)$(raw"""
---

Prose documentation with ``\LaTeX``
""")""" MyStruct
@kwdef struct MyStruct
  n::Int
end

[bzinberg]

I wonder if the above workaround (or a better version of it, if known) should be mentioned in the documentation? It seems like an important use case.