add additional function documentation and tests