Как документировать @throws в документации по интерфейсу

Я пишу библиотеку PHP, и у меня есть проблема. В моих интерфейсах есть что-то похожее на следующее:

<?php
/**
 * My interface
 *
 * ...
 */
interface MyInterface
{
    /**
     * This method does foo.
     *
     * @throws \RuntimeException If foo can't be done.
     */
    public function fooAndBar();
}
?>

Теперь запись @throwsне совсем верна, так как интерфейс на самом деле ничего не делает и используется исключительно для абстрагирования деталей реализации. . Тем не менее, я всегда использовал его, потому что все мои реализации интерфейса выдавали исключение, когда что-то пошло не так.

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

В этой ситуации, как я должен документировать @throwsв объявлениях интерфейса? Нужно ли это вообще документировать?

14
задан Mogsdad 24 January 2018 в 04:54
поделиться