Topic/plt 557

- Added ``combine`` and ``flatCombine`` methods, together with code
samples in the javadoc
- Added tests to show usage
- Minor other fixups to javadoc