Как я могу документировать исключения, которые не выбрасываются определенным методом/конструктором, но может быть брошен другим вызываемым?

Question

Скажем, у меня есть класс с тремя конструкторами, как показано ниже:

public class ExampleClass { 
    // constructor #1 
    public ExampleClass(int a) { 
     this(a, "aaa"); // "aaa" is just an arbitrary default for b 
    } 

    // constructor #2 
    public ExampleClass(String b) { 
     this(2, b); // 2 is just an arbitrary default for a 
    } 

    // constructor #3 
    public ExampleClass(int a, String b) { 
     // a has an arbitrary minimum value of 3 
     // b has an arbitrary minimum length of 3 
     if (a < 2 || b.length() < 2) { 
      throw new IllegalArgumentException("a and b cannot be less than 2"); 
     } 

     // ... 
    } 
} 

В этом случае, у меня есть три конструктора. Третий из них является своего рода основным конструктором, другие просто предоставляют значения по умолчанию, поэтому класс может быть построен только с одним значением, заданным вместо обоих. Я пытаюсь написать документацию для таких классов через JavaDoc. Если бы я должен был написать документацию для первого или второго конструкторов, использовал бы я использовать тег @throws для документирования потенциального IllegalArgumentException? Или я должен сохранить документацию только для документации третьего конструктора IllegalArgumentException? В этом случае, какой был бы лучший, наиболее подходящий способ выразить, что a должен быть выше 2 или что b должен быть длиннее 2 символов? Как я могу заявить, что можно было бы выбросить IllegalArgumentException без документирования его с помощью @throws?

Answer 1

Все три ваших конструкторами сделать сгенерирует исключение (вы можете проверить это опытным путем) - вы можете» t ожидайте, что потребитель вашего кода узнает, что происходит под обложками (т. е. проверяются ли аргументы внутри конструктора или каким-то методом, вызываемым конструктором). Таким образом, вы должны документировать все три конструктора.

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

Answer 2

Используйте отмеченные исключения, и документ для всех 3 - или сделать 1 приватным и документ для другой 2.