Resolve merge conflicts, add documentation.

Added documentation in f9f7131 so that we remember why we took this approach later on.