Define the macro API for generating metadata annotations on declarations

[munificent]

The builder API currently doesn't give you a way to add metadata annotations to declarations created by macros. There's a TODO in the proposal to allow that.

[jakemac53]

There are two aspects to this:

The ability to add annotations to existing declarations

As I have dug into this, I think it is in direct conflict with the ability to introspect on the annotations on a given declaration, and the general principal that we want to always provide "complete" results when questions are asked of a program. Multiple macros, even in the same phase, might get different answers for what the annotations are on a given declaration. At a minimum this implies ordering constraints within phase 1 and phase 3 which don't otherwise exist currently (all macros in those phases can run simultaneously today).

I also think it is much more useful to be able to introspect on annotations, compared to adding new annotations on existing declarations. So I am inclined to just not allow adding annotations to existing declarations for now.

The ability to add annotations to new declarations.

This is already possible. Whenever adding a new declaration you provide the entire thing and are allowed to include both documentation comments and metadata annotations.

[jakemac53]

I am going to put this into the backlog (specifically, adding annotations to existing declarations) to look at for future releases given the concerns I have and lack of current compelling reasons to support it.