doc: contributory behavior may be required sometimes

doc: contributory behavior may be required sometimes

While already there, hoist the explanation about contributory behavior
from RETURN VALUES to the main DESCRIPTION section.
The only reason it was in RETURN VALUES is because of historical
reasons; we used to justify why the return value was deprecated there,
so the position of the explanation made sense before removal of the
return value.