Doc system cannot document first expression generated by macro

[mauro3]

I'm pretty sure this used to work:

julia> macro mm()
           esc(quote
               g(x) = 4
               f(x) = 3
               end
               )
       end

julia> "d" @mm
ERROR: Invalid doc expression begin  # none, line 3:
    g(x) = begin  # none, line 3:
            4
        end # line 4:
    f(x) = begin  # none, line 4:
            3
        end
end

(@with_kw generates a type and the a bunch of other stuff)
I would expect that "d" gets attached to g, i.e. the first expression generated by the macro. I think this used to work. At least below used to work with an about 8 days old master (this is how I got to this) but now errors with the same error:

using Parameters

"d"
@with_kw immutable MT1
    r::Int = 4
    c = "sdaf"
end

[MichaelHatherly]

I think this used to work. At least below used to work with an about 8 days old master

@doc would probably have been documenting the last expression in the block if it was encountering a Expr(:block, ...).

I guess we could go with the behaviour of attaching the doc to the first expression in a block. There's some related discussion here about this kind of thing.

Alternatively you could allow your macro to take a string as an argument and then use @doc internally to attach the documentation to the exact object you want:

@with_kw """
...
""" immutable MT1
    r::Int = 4
    c = "sdaf"
end

though it's not quite as elegant.

[mauro3]

Yes you're right, what I should have written: it used to work in the sense that no error was thrown. I didn't actually check to which expression the doc was attached.

Your alternative suggestion would mean that all macro writers would also have to deal with documentation, not ideal. I think attaching to the first bit would be the best/logical thing to do.

[MichaelHatherly]

I think attaching to the first bit would be the best/logical thing to do.

Would that cover all macros? Are there times when some setup code is needed prior to the main definition? ie.

macro foo(...)
    quote
        # some setup code
        # ...
        $(def)
    end
end

@one-more-minute's Expr(:meta, :doc) idea would probably be the most general in that case.

[mauro3]

It would cover all macros I made which I would like to use documentation with (a grand total of 3...).

Linked in the issue you linked above I found where I discussed this before (I couldn't find it anymore): #12000 (comment). With that PR it was possible to document the return value of a block, which doesn't work anymore:

julia> "asdf" begin
       x=1
       f(t) = 5
       end

ERROR: Invalid doc expression begin  # none, line 2:
    x = 1 # line 3:
    f(t) = begin  # none, line 3:
            5
        end
end

although single statement blocks work:

julia> "asdf" begin
       x=1
       end
  asdf

So how about, instead documenting the return value of a block/macro expansion, as was possible (I think) after PR #12000 . That would work for me. It would be a bit fiddly with methods but that is ok (for now).

[MichaelHatherly]

although single statement blocks work:

That's due to unblock which is used in docm.

instead documenting the return value of a block/macro expansion

That wouldn't allow for documenting methods, types, or constants correctly I think, since if the convention was to document the value of the block then, for example:

julia> macro t()
           quote
               # ...
               type T
               end
           end
       end

julia> typeof(@t())
Void

julia> macro f()
           quote
               # ...
               f() = ()
           end
       end

julia> typeof(@f())
Function

julia> macro c()
           quote
               # ...
               const c = ()
           end
       end

julia> typeof(@c())
Tuple{}

@doc would just be getting the value of the block, which has lost some information about what's actually being documented.

[mauro3]

If documenting the return value, one would have to be explicit to return what needs to be documented:

macro t()
    quote
        # ...
        type T
        end
        T
    end
end

which would work fine for everything except methods. I would be fine with this.

[MichaelHatherly]

explicit to return what needs to be documented

Yeah, that would work. @one-more-minute are you still against documenting arbitrary blocks? Or we could try to get the Expr(:meta, :doc) idea working. I put together a quick prototype this morning. Seems to work alright.