improved function documentation