mainly changes due to several reviews

one minor bugfix and several documentation improvements