Standardize method of documenting errors in function headers

[Danp2]

See prior discussion in #444

[mlipok]

Prior discussion was not closed.
So what this new ISSUE is intended to do in a different way than prior discussion ?

[Danp2]

I never indicated that it was closed. I simply referenced it for the value it already contains. If you read the prior discussion, then it should be clear why I opened this separate PR. Let me know if you still don't understand, and I will explain further.

[Danp2]

Some related discussions --

#444 (comment)

#437

Also, this is from the wiki --

Return values

Details what is returned by the function. This often comes in the form of Success and Failure values, but this is not always the case. Any setting of the @error of @extended flags should be detailed, along with their meanings, in some cases it is enough to say that @error is set to non-zero in the event of an error, in most cases though a list of values for @error should be given.