exceptions, errors, and documentation

PEAR_Error has served me well, but errors are not as well defined in the coding standards as I would like. I think that using exceptions makes documentation more clear and easier to read. How many times have others done something similar to the following: /** * myClass for doing something * * @param string something * @return mixed success = string new_something, error = PEAR_Error object */ More often I see developers not mentioning possible PEAR_Error returns at all in the API docs. With exceptions it could just be: /** * myClass for doing something * * @param string something * @return string new_something * @throws PEAR_Exception */ I have been primarily coding PHP for the past few years, so I don't have a lot of experience with exceptions. I imagine that is also the case for others on this list. I don't want to let me ignorance and lack of experience to get in the way of simplicity and completeness. just my $0.02 -Jackson