Fix -saveSourceOutput when target is a directory

The problem is actually that the one-arg version of
OutputFileSet.openForWrite() didn't work, but it is unused
except by SourceSaver.

Wrote javadoc explaining how these methods actually work.

(The OutputFileSet classes are quite messy, but it looks like
this code is intended to avoid touching files unnecessarily
to work well with a Makefile-style build where timestamps
are used to determine whether downstream build rules need
to run. It seems fragile, but I'm ignoring that issue and
just getting -saveSourceOutput to work.)

Change-Id: Iebbad400942115c0acb34fefb1fba502ba8256d8
2 files changed