added some more documentary (and fixed some existing one)