document scrub_for_print() as it currently behaves
document scrub_for_print() as it currently behaves

Add documentation for all parameters and the return value based on the
function's current behavior.

Apparently this function was intended to behave like snprintf(), where
the output is simply truncated if the output buffer isn't big enough.
However, as currently written, the function might write past the end
of the output buffer if the output buffer isn't big enough.  Thus, in
its current state it can't be used with a small buffer, so document it
as such.

Note that this change in documented behavior means that the test cases
in stringutils-test.c now violate the API specification.  Similarly,
other users of this function might rely on support for small output
buffers.  However, future commits will change scrub_for_print() to
support truncation, so I am not going to modify any code to conform to
this new documentation.

rhansen/rpstir,rhansen/rpstir,rhansen/rpstir,rhansen/rpstir,rhansen/rpstir