Wrong assumption about @doc arguments breaks Revise

[mgkurtz]

When using Revise, I got the following error

┌ Error: Failed to revise /some/path/to/file.jl
│   exception =
│    BoundsError: attempt to access 3-element Vector{Any} at index [4]
│    Stacktrace:
│     [1] getindex
│       @ ./array.jl:861 [inlined]
│     [2] iterate(iter::JuliaInterpreter.ExprSplitter, state::Nothing)
│       @ JuliaInterpreter ~/.julia/packages/JuliaInterpreter/Q7nmG/src/construct.jl:526

which was generated by

JuliaInterpreter.jl/src/construct.jl

Line 526 in 7fe78fa

body = ex.args[4]

There it is assumed, that if is_doc_expr(ex) holds, ex.args must have length 4. But I have foolishly added a comment between my docstring and the function I documented, like

@doc "foo"
# TODO: implement this correctly ;)
foo() = 42

which resulted in @doc having only one argument and ex.args = [:@doc, LineNumberNode(...), "TODO ..."] thus has only length 3. So maybe adding this comment was foolish from me, but my follys should not break Revise from working. To settle this, perhaps is_doc_expr may get an extra line length(ex.args) == 4 || return false?

[simeonschaub]

To settle this, perhaps is_doc_expr may get an extra line length(ex.args) == 4 || return false?

This is probably reasonable either way, but that comments in the line after @doc parse this way seems like an upstream bug to me. Could you open an issue for this on the Julia repo?

[pfitzseb]

There's a typo in the OP; the comment doesn't show up anywhere after parsing:

julia> Meta.parseall("""
       @doc "foo"
       # TODO: implement this correctly ;)
       foo() = 42 
       """) |> dump
Expr
  head: Symbol toplevel
  args: Array{Any}((4,))
    1: LineNumberNode
      line: Int64 1
      file: Symbol none
    2: Expr
      head: Symbol macrocall
      args: Array{Any}((3,))
        1: Symbol @doc
        2: LineNumberNode
          line: Int64 1
          file: Symbol none
        3: String "foo"
    3: LineNumberNode
      line: Int64 3
      file: Symbol none
    4: Expr
      head: Symbol =
      args: Array{Any}((2,))
        1: Expr
          head: Symbol call
          args: Array{Any}((1,))
            1: Symbol foo
        2: Expr
          head: Symbol block
          args: Array{Any}((2,))
            1: LineNumberNode
              line: Int64 3
              file: Symbol none
            2: Int64 42

[simeonschaub]

Ah, that makes a lot more sense! In that case the check should be all that's needed

[mgkurtz]

There's a typo in the OP; the comment doesn't show up anywhere after parsing:

Sorry, perhaps I should have provided a dump as well. Of course the comments do not show up anywhere, but also the to be documented object does not show up in the @doc macrocall:

julia> Meta.parseall("""
       @doc "foo"
       # TODO: implement this correctly ;)
       foo() = 42 
       """) |> dump
[...]
    2: Expr
      head: Symbol macrocall
      args: Array{Any}((3,))
        1: Symbol @doc
        2: LineNumberNode
          line: Int64 1
          file: Symbol none
        3: String "foo"
[...]

which is actually the documented behavior. To be honest, I was actually quite confused by the fact, that the complete dump contained four arguments 😕 But the @doc macrocall, I quoted above, really has only three arguments and the fourth argument of the surrounding expression should better be in there instead of outside.

[...] that comments in the line after @doc parse this way seems like an upstream bug to me. Could you open an issue for this on the Julia repo?

Well, as it is documented, it is technically not a bug, but still strange: this code results in @doc "foo" returning the documentation of String, which is then ignored. If the @doc were not there, it would simply result in a line containing "foo", which would be ignored. I opened an upstream issue to discuss that topic.

[timholy]

Closed by #539