Javadoc @throwsエラーコードハンドラによってスローされる例外のタグ

Question

私はC ApiをJava Apiにブリッジします。 C Apiは例外的な場合にエラーコードを使用します。すべての機能は、このようなエラーコードを返し、エラーコード（約100）がたくさんあるので、私はより一般的な実行時例外の束にエラーコードを変換エラーコードのハンドラを書いた：

public class ErrorCodeHandler { 
    public static void handle(int status) { 
     switch(status) { 
      case SUCCESS: 
       return; // In case of success, simply return 
      case NO_VALID_DATA: 
       throw new DataError("No valid data"); 
      ... 
      case NO_CONNECTION: 
       throw new ConnectionError("No connection"); 
     } 
    } 
} 

すべての私カスタム例外クラスは、基本Exceptionクラスから自分のアプリケーションに固有の継承：

public class MyException extends RuntimeException { ... } 
public class DataException extends MyException { ... } 
... 

私の方法は、単にエラーコードのハンドルを呼び出すCのAPIへの呼び出しから返さ：

public void someMethod() { 
    int status = cBinding.someMethod(); 
    ErrorCodeHandler.handle(status); 
} 

エラーが発生した場合、メソッドは適切な例外をスローします。そうでなければ、それは単に戻るでしょう。

私はこの種の例外処理を文書化する方法に関する問題に直面しています。実行時の例外をthrows節として追加するのではなく、Javadoc @throwsタグを使って文書化することを読んでいます。

私の知る限りでは、メソッドから（間接的に考えられるエラーコードを参照して）スローすることができるすべての異なる例外に対して@throwsタグを追加する必要があります。私は、最初のアプローチではほとんど役に立たない@throwsタグ（これらのエラーコードの多くは非常にまれである）をたくさん使ってドキュメントを混乱させ、これらを文書化するのは非常に手間がかかるように感じます。 2番目のアプローチは主にコピー貼り付けですが、私は例外階層が私に与える優位性を失います。

誰もこれまで類似したことはありますか？この種のものを文書化する方法に関するアドバイスはありますか？

Answer 1

あなたのjavadocに@throws MyException if underlying service failsのようなものを書くのは完全に合理的です。 Java SEではかなり一般的です。例えば：

• Files.copyは、それがのIOExceptionの他の多くのサブクラスを投げることができるにもかかわらず、IOExceptionを用@throws句とのIOExceptionの2つのサブクラスがあります。
• JDBCメソッドStatement.executeには、スローされるSQLExceptionの他のサブクラスが多数あるにもかかわらず、SQLExceptionのサブクラスである@throws句とSQLExceptionのサブクラスがあります。