-
Notifications
You must be signed in to change notification settings - Fork 30
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
@template broken with Base.@__doc__? #73
Comments
Do you have a code snippet of what you mean by any chance? |
Ok a simple example that doesn't actually need the 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> |
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 |
@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 I am combining this with a different workaround, to get Documenter.jl to use the right "view source" link when combined with @doc """Fields:
$(FIELDS)$(raw"""
---
Prose documentation with ``\LaTeX``
""")""" MyStruct
@kwdef struct MyStruct
n::Int
end |
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. |
This moves the expansion of templates from macro expansion time to later on. This allows us to avoid having to search through expressions looking for the actual expression type since those may be hidden by "decorator" macros. It also handles cases where `@doc` is used on a string macro docstring, such as @doc raw"..." f(x) = x Implementation is based on a new internal abbreviation type called `Template` which gets prepended and appended to docstrings in modules where templates are available. Then, during formatting, we expand these `Template` abbreviations into there definitions. Fixes JuliaDocs#73.
@template
doesn't seem to work when a struct is processed by a macro, andBase.@__doc__
is used in the macro.The docs otherwise work fine. But the template is not inserted, although the
format
method does actually run.The text was updated successfully, but these errors were encountered: