documentation and empty list handling