Improve documentation for suites

[BillyAutrey]

The README filess for scala_test_suite and scala_library_suite are low on details. They should include a reference to the definition, a parameter list, and maybe an example of the resulting targets?

Also it's not entirely clear to me between the code and the description if this creates a target per source file, or if you can specify a whole glob (e.g., a directory) as one target.