documented functions and intent