extended the return code semantic for the list iterator

 1 go ahead with the iteration
 0 stop the iteration
-1 removes from the list and go ahead with the iteration
-2 removes from the list and stop the iteration

added documentation as well