more javadocs and comments for harmonize()