Fixed performance of TestSuite::addTestFile() + missing docs

Apologies.  My advice in #1362 was based on utterly wrong and outdated information.  It's my duty to correct that mistake.

1. https://gist.github.com/sun/287c1f75528dc75cdb96

1. Even after reviewing and studying #1362 for a while, it still wasn't clear to me why all of this futzing is necessary in the first place.  Dissecting history yielded https://github.com/sebastianbergmann/phpunit/commit/1d15545d8d77d3d1ab561e8167b90536fe4d4361 (_"5096"_ points to former issue in Trac, which no longer exists) and https://github.com/sebastianbergmann/phpunit/commit/1a5d6926442468ba19c18e6117c3afc5949f184d (same commit, but says _"Be more restrictive."_), and finally https://github.com/sebastianbergmann/phpunit/commit/8b8c705ce7dd77b02ba768d39224dddfeb34fb62 (original recreation of svn trunk in git in 2006). — Therefore, I had to reverse-engineer the original intentions in order to document what's actually going on.

  I stopped after the loop starts to prevent scope creep - even though I had to dissect the full function body in order to draw final conclusions.

  In essence, the code assumes PSR-1 [long before php-fig was a thing], one class per file, classname == filename, and uses reflection to reverse-map discovered class **short**⁣name[s] back to filename[s].  Only upon a direct match, the test class is found.  (It doesn't account for various edge-case conditions though; specifically, the `$newClasses` array is not reset to a single element if there's no direct match, in which case the entire diff/list of classes will be processed.)

  The only way around that funky logic would be to have direct access to the active classloader(s), which would allow to manually reverse-map a filesystem path to a classname.
Nope (because basename of a filename), but the file's basename can still contain characters that are reserved in PCREs.  `preg_quote()` must always be used whenever the subject contains arbitrary external input.