Changed docs/comments after review suggestions.

Suggestions from B. Skaflestad and A. Lauser.