Update docstrings and comments in code

[PokhodenkoSA]

Before fixing you should find a procedure for finding uncommented code.

[diptorupd]

The issue is too broad to deal with. When we start fixing the API documentation, a more narrowly targeted issue will be opened.