move logic to javadocs