update explanatory comments