#225: update documentation

Add some documentation for the changes made in pull request #712.