FWIW, the issue with MirrorsUsed is not simply documentation. It goes much deeper. We still have not figured out the best (or even a good) model for how to communicate information about reflective usage to the system. MirrorsUsed is a stop-gap. Once we know how it should work, we can document it.

But... it's what we're telling people to use, for now. Can't we do just a wee bit of doc? The constructor has no description at all, so I have no idea of what "targets" and "metaTargets" mean, e.g.

Reassign to dart2js land.

Set owner to @floitschG.

Removed Area-Documentation, Type-Defect, Priority-High labels.
Added Area-Library, Type-Documentation, Priority-Medium labels.

Copied from internal bug-tracker (thanks Chris):

MirrorsUsed has been around for >= 1.5 years, yet its api remains too non-committal to be useful, e.g.
"For now, there is no formal description of what a reflective target is.
Informally, it is a list of things that are expected to have fully functional mirrors."
that's too vague.

here are some docs, just to show the level of specificity that would make it usable,
but please don't just copy this since i made up half of it:

• the following are acceptable values for targets:
    - a comma-separated string of other strings S, where S represents the set of libraries L
      s.t. the name of L is either S or S followed by a dot followed by something else.
      any amount of whitespace after each comma is allowed.
    - a list of strings, each of which will be interpreted as either a full library name, not a prefix, or a symbol name, like 'String',
      and these can be mixed and matched.
    - a list of type objects.
    you may not mix and match the above types (highly speculative. i totally made that up).
• override, when used in library L0, must be a list of library names (not prefixes) or the string '*', representing all libraries.
    each library L it represents, except for L0 itself, will have the property that any @­MirrorsUsed in L will be ignored and instead,
    this @­MirrorsUsed will supercede that one... except if both use override, in which case... i have no idea.
• the definition of "class used as metadata" is... no idea. and so the difference between targets and metaTargets is... no idea.
  if, after applying the above rules, library L0 allows reflecting upon class C, or library L, or symbol S, then
  every method M in L has the property that when M is at the top of the call stack, a reflective call on C or L or S will succeed.
  but it will fail if M calls M' in library L' and L' does not declare the ability to reflect on C or L or S.

  ---

  cc @trinarytree.
  Set owner to @herhut-ggl.

Added Started label.

I improved the dartdoc for MirrorsUsed in

https://codereview.chromium.org/1122983002/

The purpose is not to discuss the design of MirrorsUsed but merely describe the behaviour of the current implementation in dart2js.

Comments here or on the CL most welcome.

This has now landed in r45585.

Added Done label.