SamUtils PairOrientation is confusingly ambiguous about paired reads needing to map to the same contig

[yfarjoun]

• Improved documentation to clarify that PairOrientation (in SamUtils) pertains only to reads on the same contig.
• Now getPairOrientation will throw an exception if thrown when the two reads are mapped to different contigs
• Added tests to verify that the exception is thrown in the 4 cases specified.

Description

Please explain the changes you made here. Explain the motivation for making this change. What existing problem does the pull request solve?

Things to think about before submitting:

• [x] Make sure your changes compile and new tests pass locally.
• [x] Add new tests or update existing ones:
  • A bug fix should include a test that previously would have failed and passes now.
  • New features should come with new tests that exercise and validate the new functionality.
• [x] Extended the README / documentation, if necessary
• [x] Check your code style.
• [x] Write a clear commit title and message
  • The commit message should describe what changed and is targeted at htsjdk developers
  • Breaking changes should be mentioned in the commit message.