docs done -- going back to code comments
(cherry picked from commit 5e3f783a231ced7d41188499614678b59015e242)