Документирование выброшен RuntimeExceptions для интерфейсов

Question

У меня есть следующий интерфейс:

public interface DataReceiver { 
    public Data getData(); 
} 

Приемники бетона имеют разные источники данных и, следовательно, бросить различные исключения:

public class DeviceDataReceiver implements DataReceiver { 
    // Gets data from some hardware device 
    // Exceptions include: DeviceNotConnected, DeviceNotLicensed, RequestTimeout, etc 
    public Data getData() { ... } 
} 

public class FileDataReceiver implements DataReceiver { 
    // Gets data from a file on disc 
    // Exceptions include: FileNotFound, BadFormat 
    public Data getData() { ... } 
} 

Я документированы эти RuntimeExceptions в Предос- классов, используя тег Javadoc @throws.

То, с чем я борюсь, заключается в том, как документировать интерфейс, поскольку это будет первое, на что смотрит пользователь моей библиотеки, когда он получает сообщение об ошибке (я использую интерфейс по всему публичному API вместо конкретных классов). Документирование всех исключений из производных классов не очень привлекательно для меня, поскольку они вообще не имеют отношения.

Любые лучшие практики для этого сценария?

Answer 1

Что я борюсь с как документировать интерфейс, так как он будет первым, что пользователь моей библиотеки смотрит на, когда он получает ошибку (я использую интерфейс на протяжении всего моего публичного API вместо классов ). Документирование всех исключений из производных классов звучит не очень привлекательно для меня, так как они вообще не имеют отношения .

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

Если вы считаете, что эти исключения не являются первичными для проверки и обработки (или выброса), я также не думаю, что вам нужно ссылаться на них в интерфейсе. Кроме того, теоретически, интерфейсы не должны сочетаться с реализациями в их спецификации.
Однако вы можете указать в методах интерфейса, что в соответствии с реализациями, оно может вызывать RuntimeException подклассы.
Кроме того, если вы освоите источник кода этих исключений, возможно, вы могли бы использовать абстрактный класс для исключений (исключений) предков и сделать наследование ваших подклассов в этом абстрактном классе. Таким образом, вы можете записать это супер исключение в свой интерфейс.

Наконец, ваш дизайн поощряет ваших клиентов не программировать по интерфейсу при использовании подклассов DataReceiver, поскольку в противном случае клиенты рискуют не иметь конкретного javadoc, и они не будут непосредственно видеть конкретные исключения, которые могут вызывать методы реализации, которые используют.
Итак, возможно, вы также должны точно определить его в интерфейсе.