Update code documentation

Change the annotation alongside the third case to make
its behaviour a little clearer.
Merge branch 'master' into gh-pages