Document issue 2 and 3; hide implementation; move constructors to companion object