Added more documentation on the various gotchas.