revised documentation for functions