documented functions