I think that there are two types of return values of shell functions: the exit code and the standard output. The exit code of a function can be checked for errors and the standard output is usually used as values(call by ref).

if number_of_procs=$(nproc); then # do something with number_of_procs else # handle error fi

Now, let's say nproc is a shell function rather than the binary. How would you document \retval(the standard output - number of threads) and \exitcode(0 on success, 1 on error)?