Add macro error help trace for the users

[BrucePerens]

One of the most difficult things about the Lucky Framework for me is that my programming errors often show up in the middle of macro code instead of where I wrote them. I found that I can add help for the programmer in my macros, which is shown in the error report from --error-trace and does not add space in the compiled code. Here is some sample macro code to demonstrate what I'm doing:

macro delegate2(name, to, file = __FILE__, line = __LINE__)
# This method was generated through an invocation of
# `{{@type.name}}.delegate2 {{name}}, to: {{to}}`
# at {{file.id}}:{{line.id}}.

When I test the code with a deliberately-injected error, I get this output from crystal build --error-trace. The "target method" lines would not apply to Lucky most of the time, but the information for that comes from The ASTNode and @type. Every ASTNode includes ASTNode#filename and ASTNode#line_number, you don't strictly have to pass __FILE__ and __LINE__.

There was a problem expanding macro 'delegate2'

Called macro defined in delegate.cr:2:3

 2 | macro delegate2(name, to, file = __FILE__, line = __LINE__)

Which expanded to:

 >   1 |    
 ... (blank lines)
 >  31 |        
 >  32 |        # This method was generated through an invocation of
 >  33 |        # `A.delegate2 inspect, to: @a`
 >  34 |        # at /home/bruce/Crystal/delegate/src/delegate.cr:46.
 >  35 |        # The target method is at
 >  36 |        # /usr/share/crystal/src/reference.cr:71
 >  37 |        def inspect(io : IO) : Nil 
 >  38 |          @a.inspect(io) 
 >  39 |          @a.foobar
 >  40 |        end
 >  41 |        
... (blank lines)
 >  74 |        
 >  75 |        # This method was generated through an invocation of
 >  76 |        # `A.delegate2 inspect, to: @a`
 >  77 |        # at /home/bruce/Crystal/delegate/src/delegate.cr:46.
 >  78 |        # The target method is at
 >  79 |        # /usr/share/crystal/src/object.cr:155
 >  80 |        def inspect(io : IO) : Nil 
 >  81 |          @a.inspect(io) 
 >  82 |          @a.foobar
 >  83 |        end
 >  84 |        
... (blank lines)
 >  93 |        
 >  94 |        # This method was generated through an invocation of
 >  95 |        # `A.delegate2 inspect, to: @a`
 >  96 |        # at /home/bruce/Crystal/delegate/src/delegate.cr:46.
 >  97 |        # The target method is at
 >  98 |        # /usr/share/crystal/src/object.cr:143
 >  99 |        def inspect() : String 
 > 100 |          @a.inspect() 
 > 101 |          @a.foobar
 > 102 |        end

The progam containing this is at https://github.com/BrucePerens/delegate

[matthewmcgarvey]

@BrucePerens I think you're on to something here. Even if it's not as heavy as your example, adding in little comments can help a ton when we can't catch it ourselves. Here's an example of a simple comment in a macro that was just added to Lucky: #1321

I don't know how Crystal chooses how much to show in the error output vs the output with --error-trace but I would prefer we try to get these comments to show up in the output without having to pass the error trace flag if at all possible.

[BrucePerens]

@matthewmcgarvey The solution is probably to designate an annotation that will be emitted with compiler error tracing.