Merge pull request #912 from r1chardj0n3s/master

Another small documentation addition.
mention more clearly the arguments and the return value