Documentation error tag
I have a method in a class where I am throwing an error.
/**
* Get info
* @return string|FALSE Info
*/
public function getInfo()
{
if ($this->info) {
return $this->info;
}
trigger_error('Missing info', E_USER_WARNING);
return FALSE;
}
I don't want to throw an exception here, as I really need / need this code to continue working. Elsewhere I am logging this error and the registration error is outside the scope of this class.
But how should I document this? For the exception, I would use:
/**
* @throws Exception
*/
Is there something similar for errors? I really want other developers to easily know what's going on in my code.
source to share
I agree with others that I would change my approach to coding here, but to address your direct question - I would perhaps use the @internal tag to explain what you want developers to know about. Of course, when you run phpDocumentor against this code, @internal tags won't show up in your generated documents unless you use the -parse-private runtime option ... this is because internal-info-for-devs is supposed to be disabled limits for API-oriented consumers / readers, as well as "@access private" elements.
source to share
There is no phpdoc tag for errors.
trigger_error()
returns bool, so your method doesn't return or throw anything. Execution will resume unless your error handler prevents this from happening, so using @return or @throws will misuse them and will probably confuse anyone reading your code.
I would use a different approach.
This is how I would do it:
/**
* Has info
*
* @return bool Whether info is available
*/
public function hasInfo()
{
return (bool) $this->info; // or use isset() or whatever you need
}
/**
* Get info
*
* @throws Exception
* @return string The info string
*/
public function getInfo()
{
if (! $this->hasInfo()) {
throw new Exception('Missing info');
}
return $this->info;
}
And then from your other code, you can do:
if ($object->hasInfo()) {
$info = $object->getInfo();
} else {
// no info!
}
I will also catch Exceptions at the root of my codebase:
try {
MyApp::run();
}
catch(Exception $e) {
// handle error, eg. display fatal error message
}
source to share