added documentation for the return values