fix to list, and improve docs for list