#141 Added comments from Code Review

Created by: mattclarke

https://github.com/ess-dmsc/kafka-to-nexus/issues/141

These are the code comments that were added during the Code Review on 9th March 2018.

I have given them doxygen formatting and modified some existing comments.