Add tests for a function that currently does not appear to be tested.
Rewrite documentation for a function.
Rewrite parts of the implementation to make it easier to read.
Merge pull request #281 from bangerth/doc-updates-and-test-additions

Doc updates and test additions