more functions documented in javadoc style