LOTS OF DOCUMENTATION. closes #432