some documentation of the new functions