Document some of the point internals

This adds a bit of documentation to where the previous set of
points are updated with the new values.  It also documents a
known race condition is being worked around.
Document what the `color` function actually does

This documents the arguments used for converting the color mode
of the internal image along with the different outputs from the
function.