#87 more documentation
#87 better code assertions