You won’t need to directly use Markdown.parse(docstr), since that’s what
julia does for you anyway, see here
<https://github.com/JuliaLang/julia/blob/baf174f5c252a438006c6f23ed7097fbab004025/base/docs/Docs.jl#L437-L443>,
where any plain string or interpolated string expression gets wrapped in a
markdown parsing call automatically when passed to @doc.
Also, note that defining new variables inside the returned block, in this
case dot_op and docstr, will be visible (though gensym’d) from the calling
env, ie.
macro foo_op(op)
quote
dot_op = symbol(".$($op)")
docstr = "`$($op)` also works for `Foo` types!"
function Base.$op(a::Foo, b::Foo)
Foo(dot_op(a.x, b.x))
end
@doc Markdown.parse(docstr) Base.$op
Base.$op
end
end
julia> @foo_op +
julia> names(Main)
10-element Array{Symbol,1}:
symbol("#3#dot_op")
symbol("#4#docstr")
symbol("@foo_op")
:Base
:Core
:Foo
:Main
:User
:__META__
:ans
Notice symbol("#3#dot_op") and symbol("#4#docstr"). Each time you call the
macro you’ll generate a new pair. They won’t clash with any other
variables, but it’s worth trying to avoid creating them to keep the
namespace clean. Both the variables aren’t really needed anyway since docstr's
value could just be placed directly into the @doc.
The other variable, dot_op, might actually cause some trouble
(performance-wise) since you’re defining a non-const global that aliases a
function and then calling it from inside a function. Compare the output of
the @code_* macros for your macro and the following
version that doesn’t define temporary variables:
julia> macro foo_op_direct(op)
quote
function Base.$op(a::Foo, b::Foo)
Foo($(symbol(".", op))(a.x, b.x))
end
@doc "`$($op)` also works for `Foo` types!" Base.$op
Base.$op
end
end
julia> type Foo
x :: Int
end
julia> @foo_op_direct +
+ (generic function with 166 methods)
julia> code_llvm(+, (Foo, Foo))
...
The code generated by @foo_op_direct will be quite a bit shorter than that
of @foo_op.
— Mike
On Thursday, 17 December 2015 07:16:09 UTC+2, Ismael Venegas Castelló wrote:
>
> I didn't know of "$($x)" to interpolate inside stirng inside expresion,
> thanks!
>
> This also works:
>
> macro foo_op(op)
> quote
> dot_op = symbol(".$($op)")
> docstr = "`$($op)` also works for `Foo` types!"
> function Base.$op(a::Foo, b::Foo)
> Foo(dot_op(a.x, b.x))
> end
> @doc Markdown.parse(docstr) Base.$op
> Base.$op
> end
> end
>
> El miércoles, 16 de diciembre de 2015, 11:19:24 (UTC-6), Michael Hatherly
> escribió:
>>
>> If the macro returns a single documentable expression, such as a function
>> or type, then you shouldn’t need to do anything special, just add an @doc
>> to the for-loop that generates the methods.
>>
>> If the macro returns a block expression then you need to tell the
>> docsystem how you’d like to handle it. Use Base.@__doc__ to mark the
>> subexpression you’d like to document in expression returned by the macro.
>> See this section of the manual,
>> http://docs.julialang.org/en/latest/manual/documentation/#macro-generated-code,
>>
>> for an example. Something like the following should work for the code in
>> this thread:
>>
>> macro operator_obs(name)
>> M = esc(:M)
>> n = esc(name)
>> d = esc(symbol(".", name))
>> quote
>> import Base: $n
>> Base.@__doc__ $(n)(m_1::$M, m_2::$M) = $(M)($(d)(m_1.a, m_2.a),
>> $(d)(m_1.b, m_2.b))
>> end
>> end
>>
>> for op in [:+, :-, :*, :/]
>> @eval begin
>> @doc "`$($op)` docs for type `M`." ->
>> @operator_obs $op
>> end
>> end
>>
>> help?> M(1, 2) + M(2, 3)
>> + docs for type M.
>>
>> help?> M(1, 2) / M(2, 3)
>> / docs for type M.
>>
>> Documenting code generated by a function, rather than a macro, isn’t
>> going to be as clean though. You’d need to use @doc after defining the
>> code, perhaps something like:
>>
>> for op in [:+, :-, :*, :/]
>> @eval begin
>> operator_obs($op)
>> @doc "`$($op)` docs for type `M`." $(op)(::M, ::M)
>> end
>> end
>>
>> to add docs to the correct op method.
>>
>> — Mike
>>
>>
>>
>> On Wednesday, 16 December 2015 17:41:36 UTC+2, j verzani wrote:
>>>
>>> While this topic is active, can anyone suggest how this can be
>>> incorporated with docstrings to add help entries to the newly generated
>>> methods?
>>>
>>> On Wednesday, December 16, 2015 at 5:22:24 AM UTC-5, Greg Plowman wrote:
>>>>
>>>> I have exactly the same requirement.
>>>> Additionally, I often have more than 2 fields and also change the
>>>> fields of my custom types.
>>>>
>>>> So I use a slightly more general version of the above:
>>>>
>>>>
>>>> function CompositeBinaryOp(T::Symbol, op::Symbol)
>>>> expressions = [ :($op(x1.$field, x2.$field)) for field in
>>>> fieldnames(eval(T)) ]
>>>> body = Expr(:call, T, expressions...)
>>>> quote
>>>> function $op(x1::$T, x2::$T)
>>>> return $body
>>>> end
>>>> end
>>>> end
>>>>
>>>> type M
>>>> a
>>>> b
>>>> end
>>>>
>>>> import Base: +, -, *, /, ^
>>>>
>>>> for T in [:M]
>>>> for op in [:+, :-, :*, :/, :^]
>>>> #eval(CompositeBinaryOp(T, op))
>>>>
>>>> code = CompositeBinaryOp(T, op)
>>>> println(code, "\n")
>>>> eval(code)
>>>> end
>>>> end
>>>>
>>>>
>>>> The advantage here for me is that I can change the fields (number, type
>>>> order etc.) and operators don't need manual updating.
>>>>
>>>> I have similar functions for copy constructors, unary operators etc.
>>>>
>>>
