Add the missing RETURN VALUES section and reorder the content

Add the missing RETURN VALUES section and reorder the content
accordingly.  Make some statements more precise, and point out
some dangerous traps in these ill-designed interfaces.
Also do some minor polishing while here.

Triggered by OpenSSL commit 1f13ad31 Dec 25 17:50:39 2017 +0800
by Paul Yang, but not using most of his wording because that is in
part redundant, in part incomplete, and in part outright wrong.