add docstrings to get_num_* functions
add some docstring return info