For all routines that can return NULL on error, mention this in the
function's @return docs. In cases where a small number of situations
result in this return, move the docs to the @return; in other cases just
state the NULL return briefly and leave the elaboration in the body.