expanded some remaining points in the documentation