Clarify documentation for comboIter and permuteIter

[jwood000]

Currently, in the many examples involving combo/permuteIter, we take advantage of the fact that they return FALSE when iteration is complete, however it isn't documented anywhere.

Could we explicitly document this and maybe add more explanation behind the motivation of this design?

[jwood000]

We changed how iterators are handled by in db7cce2d13.

Instead of returning FALSE when iteration has been exhausted, we return NULL.

We initially thought that returning a logical made sense as it was in line with std::next_permutation from C++, however this causes problems when the source vector is logical or the FUN parameter is a logical check.