Why @doc does not work inside a function?

General Usage
1 
using Markdown
function doc(fun)
       @show(html(@doc(fun)))
end

@doc(sin)
  sin(x)

  Compute sine of x, where x is in radians.

  sin(A::AbstractMatrix)
...

julia> doc(sin)
html(#= REPL[2]:2 =# @doc(fun)) = "<p>No documentation found.</p>\n<p>Binding <code>fun</code> does not exist.</p>\n"
"<p>No documentation found.</p>\n<p>Binding <code>fun</code> does not exist.</p>\n"
2

Shall I open an issue with this?

3

It does what you tell it to:

julia> @doc(fun)
  No documentation found.

  Binding fun does not exist.
4

Hmm, thanks but very trick. So how do I do to capture the output of @doc inside a function? And why does typeof() sees that fun is a variable but @doc takes it literally?

julia> function doc(fun)
       @show(typeof(fun))
       @show(html(@doc(fun)))
       end
doc (generic function with 1 method)

julia> doc(sin)
typeof(fun) = typeof(sin)
html(#= REPL[8]:3 =# @doc(fun)) = "<p>No documentation found.</p>\n<p>Binding <code>fun</code> does not exist.</p>\n"
"<p>No documentation found.</p>\n<p>Binding <code>fun</code> does not exist.</p>\n"
5

For the practical side, I solved the problem by calling Base.Docs.doc(fun) instead of @doc(fun).

6

Macros are “run” at macroexpansion time which is before the function is run. In other words, macros operate on syntax. The correct thing is indeed to use a function here instead of a macro.

1 Like
7

Would you please show how to use Base.Docs.doc(fun)?