Improve PGP encrypt/decrypt file JavaDoc

Improvements to the JavaDoc for the PGP APIs involved in file encryption/decryption (i.e. as used by the PBEFileProcessor sample).

I've tried to write them to aid discovery/usage - i.e. starting at PGPObjectFactory and PGPEncryptedDataGenerator leading someone to the types/methods they can use in the magic untyped streams.
There's a chance the docs are over-trained on the file encryption/decryption case (I haven't used the keyring/public key encryption side of things), so feel free to tinker or ask me to improve.

Also a few minor code changes (removing redundant methods/code) and a bunch of TODOs I didn't feel qualified to hack.