document more closely from which context certain functions may be called