Update the "pub run" documentation to reflect current behavior

[nex3]

The documentation for pub run is outdated—it's no longer valid to use pub run foo/bar to run the file foo/bar.dart. There are now three valid ways of specifying the executable:

• dart_style:format means "run the format executable from the dart_style package".
• test means "run the test executable from the test package". It's equivalent to test:test. This only applies if a Dart identifier is passed.
• bin/test.dart means "run the bin/test.dart file in the current package". This only applies if the path is not a Dart identifier.

[nex3]

I misremembered and misread the code; the current documentation is actually fine.

[skybrian]

The documentation still looks wrong to me. Specifically:

$ pub run foo arg1 arg2
This command looks in your package’s bin directory for the specified script and invokes it, passing in any arguments.

The example is using a Dart identifier, but the explanation is for when the user typed "foo.dart".

It seems like the docs should say what you just said in https://github.com/dart-lang/pub/issues/1428#issuecomment-230909731, explaining the difference between running "foo.dart" versus "foo".

[Sfshaza]

This issue was moved to dart-lang/site-www#35