Docs enhancements (rebased onto develop)



This is the same as gh-339 but rebased onto develop.

----

Include deprecated methods in the Javadocs and add a legend to the supported formats table.  Requested by @manics and @hflynn.