some more documentation (still incomplete)