Ошибка при регистрации документации

Question

У меня есть метод в классе, где я вызываю ошибку.

/** 
* Get info 
* @return string|FALSE Info 
*/ 
public function getInfo() 
{ 
    if ($this->info) { 
     return $this->info; 
    } 

    trigger_error('Missing info', E_USER_WARNING); 
    return FALSE; 
} 

Я не хочу здесь исключать исключение, так как мне действительно нужен/нужен этот код для продолжения работы. В другом месте я регистрирую эту ошибку, и ошибка регистрации выходит за рамки этого класса.

Но как я могу это документировать? Для исключения я бы использовал:

/** 
* @throws Exception 
*/ 

Есть ли что-то подобное для ошибок? Я действительно хочу, чтобы другие разработчики легко знали, что происходит в моем коде.

Answer 1

Я согласен с другими в том, что я бы изменил свой подход к кодированию здесь, но обратился к вашему прямому вопросу - я возможно, использовал тег @internal, чтобы объяснить то, что вам нужно разработчиков, о которых нужно знать. Конечно, когда вы запускаете phpDocumentor против этого кода, теги @internal не будут отображаться в ваших сгенерированных документах, если вы не используете параметр -parse-private runtime ... это связано с тем, что предполагается, что internal-info-for-devs выключен лимиты для потребителей/читателей, ориентированных на API, так же, как и элементы «@access private».

Answer 2

Для ошибок не существует тега phpdoc.

trigger_error() возвращает bool, поэтому ваш метод не возвращает и не бросает ничего. Выполнение возобновится, если ваш обработчик ошибок не предотвратит это, поэтому использование @return или @throws будет неправильно использовать их и, вероятно, смущает любого, кто читает ваш код.

---

Я бы использовал другой подход.

Это, как я хотел бы сделать это:

/** 
* 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; 
} 

, а затем с другого кода, вы можете сделать:

if ($object->hasInfo()) { 
    $info = $object->getInfo(); 
} else { 
    // no info! 
} 

Я хотел бы также перехватывать исключения в корне моего кодовую:

try { 
    MyApp::run(); 
} 
catch(Exception $e) { 
    // handle error, eg. display fatal error message 
}