Annotate + documentation.

While debugging #740 I had a 'hard' time to debug. This PR helps a little.