Inline documentation improvement

Inline documentation is only great only if it is updated along with the code. :-/ Related to 727781c