*Well Leah’s already answered this while I was fighting with my formatting,
but here’s mine anyway :)*
Welcome to the shed :) I really like that syntax and if it’s possible to
get it to work that would be really nice.The problem is that a @doc_str
macro wouldn’t capture the Expr that is being documented. See the dumps
below:
julia> dump(quote
doc"
Markdown formatted text goes here...
" ->
function myfunc(x, y)
x + y
end
end)
Expr
head: Symbol block
args: Array(Any,(2,))
1: Expr
head: Symbol line
args: Array(Any,(2,))
1: Int64 3
2: Symbol none
typ: Any
2: Expr
head: Symbol ->
args: Array(Any,(2,))
1: Expr
head: Symbol macrocall
args: Array(Any,(2,))
typ: Any
2: Expr
head: Symbol block
args: Array(Any,(2,))
typ: Any
typ: Any
typ: Any
julia> dump(quote
@doc """
Markdown formatted text goes here...
""" ->
function myfunc(x, y)
x + y
end
end)
Expr
head: Symbol block
args: Array(Any,(2,))
1: Expr
head: Symbol line
args: Array(Any,(2,))
1: Int64 3
2: Symbol none
typ: Any
2: Expr
head: Symbol macrocall
args: Array(Any,(2,))
1: Symbol @doc
2: Expr
head: Symbol ->
args: Array(Any,(2,))
typ: Any
typ: Any
typ: Any
@doc_str takes the contents of the string in as an argument (you can pass
some flags in as well, see the Regex syntax for examples) and not the Expr
appearing after. The @doc macro takes a varargs macro doc(args...) and so
can capture everything after. The trick is the -> which does “line
continuation” (or something like that).
The -> also allows Docile to capture line number information of things
other than method definitions. If you’ve looked at the generated docs for
Docile you’ll see that everything has file and line number information
provided.
Glad you’re excited. Give me a shout if you run into any issues.
