Documentation errors tag

Question

I have a method in a class where I am triggering 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 do not want to throw an exception here, as I really want/need this code to continue running. Elsewhere, I log this error, and logging error is out of the scope of this class.

But how do I document this? For an exception I would use:

/**
 * @throws Exception
 */

Is there something similar for errors? I really want other developers to easily know what is going on in my code.

Answer 1

I agree with others that I would change my coding approach here, but addressing your direct question -- I would perhaps use the @internal tag to explain the things you're wanting developers to be aware of. Granted, when you run phpDocumentor against this code, @internal tags won't appear in your generated docs unless you use the --parse-private runtime option... this is because internal-info-for-devs is presumed to be off limits to consumers / API-interested readers, just like "@access private" items are.