Re: exceptions, errors, and documentation

Hi Jackson Miller, you wrote: > 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. I usually do it as follows: /** * Do Something * * Does something. * * Returns PEAR_Error PACKAGE_E_ERRORCODE if something bad happens. * (or for more possible pear errors) * Returns PEAR_Error if: * o something bad happens * o something really bad happens * (and make an possible-error-values table in docbook) * * @access public * @return mixed Returns true on success or PEAR_Error on failure. */ > > With exceptions it could just be: > > /** > * myClass for doing something > * > * @param string something > * @return string new_something > * @throws PEAR_Exception > */ And appending PACKAGE_E_* to @throws and you're done. > 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. ACK Regards, -- Michael - < mike(@)php.net >

Attachment: [application/pgp-signature] OpenPGP digital signature signature.asc