Improve documentation

[reachfh]

Improve documentation / comments. No code changes.

[k32]

Hi, thanks for the PR! And apologies for slow responses. I have only one small comment, everything looks good otherwise.

[CLAassistant]

Thank you for your submission! We really appreciate it. Like many open source projects, we ask that you sign our Contributor License Agreement before we can accept your contribution.
_{You have signed the CLA already but the status is still pending? Let us recheck it.}