Improve scala.io.Source documentation

- fixes several typos
- clarifies non-obvious parameters
- adds code formatting and external class references

For methods with obvious parameters, I omitted ``@param`` documentation.  In all cases, I omitted the ``@return`` doc.

There are no code changes in this commit.
Maybe add a reference to what is meant by `FileSystem`.