Code review changes

Some fixes based on code review by Mark Nielsen and addition of some
PHPDocs comments.