improved documentation of a function