Change short_reference for top-level methods to ::foo

[straight-shoota]

I'm proposing to change the notation for Def#short_reference and Macro#short-reference for the top-level scope from top-level foo to ::foo.

The short_reference format is Type#def/Type.def for most defs and methods. Only for those in the top-level scope the format is top-level foo.
I think the more commonly used notation is actually ::foo with double colon indicating the top-level scope. This is more succinct and unambiguous. It fits better to the other notations in being syntactical instead of a textual description.

As far as I can tell, short_reference is currently used in three locations. The expected effects of this change would be as follows:

• Deprecation messages: (note: I think adding method would be an improvement in either case)
  • Before: Warning: Deprecated top-level foo. Do not use me
  • After: Warning: Deprecated ::foo. Do not use me
• Error in def return type restriction vs. actual return type:
  • Before: method top-level foo must return Int32 but it is returning Char
  • After: method ::foo must return Int32 but it is returning Char
• Tool unreachable:
  • Before: foobar.cr:1:1 top-level foo 3 lines
  • After: foobar.cr:1:1 ::foo 3 lines

[HertzDevil]

I wonder if we should do this to macro methods too: (this is the global namespace inside macro expressions, not the top-level namespace in the normal language)

# Crystal::MacroInterpreter#interpret_run
{% run %} # Error: wrong number of arguments for top-level macro 'run' (given 0, expected 1+)

# src/compiler/crystal/macros/methods.cr#full_macro_name
{% env %} # Error: wrong number of arguments for top-level macro 'env' (given 0, expected 1)

They could become:

{% run %} # Error: wrong number of arguments for macro '::run' (given 0, expected 1+)
{% env %} # Error: wrong number of arguments for macro '::env' (given 0, expected 1)

There is also the undefined method error:

# Crystal::Call#raise_undefined_method
foo   # Error: undefined local variable or method 'foo' for top-level
1.foo # Error: undefined method 'foo' for Int32

class Foo
  foo # Error: undefined local variable or method 'foo' for Foo.class
end

This error doesn't use the method notation, but we could reword it like so:

# the duplicated name could probably use some improvement
foo   # Error: undefined local variable 'foo' or method '::foo'
1.foo # Error: undefined method 'Int32#foo'

class Foo
  foo # Error: undefined local variable 'foo' or method 'Foo.foo'
end

[straight-shoota]

@HertzDevil Yeah, that makes a lot of sense!

[straight-shoota]

#14071 was merged for defs, we're still missing the same for macros.