Add basic API documentation to ParsedFile.to_file.

Up to now, this function had not been documented. It has been trivial until
now, but is due to implement more flexibility.
(#593) parsedfile: add support for native file headers

Some managed configurations (notably the vixie cron crontabs) are
automatically prefixed with headers not unlike those generated by
puppet providers themselves. This can lead to "mutual 1up" situations
in which puppet and the third party software will insert header upon
header in their respective output.

This change introduces the a "native header" for a parsed file. Providers
can define a regex object that will be used to identify the part of a parsed
file that comprises such a vendor header.

When writing the content back to disk, puppet will try and insert
its own header underneath the vendor's headers. Additionally, providers
can override a "drop native headers" field in order to have puppet
skip the vendor header alltogether when writing file contents. This allows
"smart" software like vixie cron to manage its header on its own.
(#593) crontab: drop vixie cron headers when writing crontabs

This makes use of the "native header" of parsed files.

Vixie cron headers should never be written back to disk, because
cron will insert a new header, regardless of what's found in the
temporary input file.
api update
whitespace and logic fixes
comment on regex
FAILED: test the new native_header feature in parsedfile

This approach is flawed.

The fixture in and of itself is fine. It cannot be fed to the parsedfile
provider itself, though. The provider is basically abstract and must be
inherited to work. The inheriting provider must populate @record_types
using the record_line function. Can we stub parsedfile thus?