Javadoc, “ exception not thrown” in Eclipse

问题: When creating a javaodc, you describe the exceptions your methods can throw, right? Take a look at the examlple: public void createLogFile() { try { file....

问题:

When creating a javaodc, you describe the exceptions your methods can throw, right?

Take a look at the examlple:

public  void createLogFile() {
    try {
        file.createNewFile();
        fileWriter = new FileWriter(file);
        bufferedWriter = new BufferedWriter(fileWriter);

    } catch (IOException e) {
        MainScene.ausgabeText.setText("Fehler bei dem Erstellen des Log Files.");

    }
}

That is my javadoc for this method.

/**
 * A logfile will be created
 * @exception IOException
 *                When the log file coulndt be created ( just a test :-))
 */

When exporting to a javadoc, Eclipse tells me:

error: exception not thrown: java.io.IOException
 * @exception IOException

But Eclipse wants me to catch that Exception.

Why is my Eclipse giving me the error message above?


回答1:

When you write a method, the implementation is hidden from the caller (ignore the fact that you can see the method implementation if you yourself wrote it). Sometimes in your implementation of a method, you will encounter exceptions (or you might even throw custom exceptions). There are two things you can do:

Catch

You can catch an exception when you want to handle it. That means that you know something could go wrong and you know what to do so that the program can continue in a predictable manner if that happens.

Since the caller cannot see your implementation, it is totally hidden from them.

Throws

When you do not want to handle the exception, because it is more suitable for the caller to be aware of this problem and handle it. In this case, you do not catch it and adds that Exception to the method via throws keyword. When you do this, you may add a @throws or @exception annotation in the method Javadoc to tell the caller exactly when they would expect to receive the particular exception.

Since that annotation only serves to tell the caller when to expect and how to properly handle the exception thrown by the method, then it is pointless to add any exception that is not thrown by the method.

Note that you are only required to throws checked exceptions. Methods do not need to list the unchecked exceptions via throws, as they are usually caused by poorly written codes.


回答2:

The function should throws Exception which you define in javadoc comment. Actually you are not throwing an IOException. You are catching it.

public  void createLogFile() throws IOException {
    try {
        file.createNewFile();
        fileWriter = new FileWriter(file);
        bufferedWriter = new BufferedWriter(fileWriter);

    } catch (IOException e) {
        MainScene.ausgabeText.setText("Fehler bei dem Erstellen des Log Files.");

    }
}

回答3:

There is 2 way to deal with Exception:

  1. Catch it inside the method, outside the method no-one will know that an Exception occurs, and so you can't write in the Javadoc that this metho will throw an Exception (implicitly throws outside)

    /**
    */
    public void createLogFile() {
        try {
            //...
        } catch (IOException e) {
            //...   
        }
    }
    
  2. You let the Exception propagates outside your method, and in that case you can writ in the Javadoc that this method can throws an Exception (implicitly throws outside)

    /**
    * @throws IOException When the log file coulndt be created
    */
    public void createLogFile() throws IOException  {
       //...
    }
    

As a note : the tags @throws and @exception are synonyms. Ref


回答4:

You shouldn't include IOException to Javadocs @throws clauses because you never throw one.

Apparently, Eclipse tries to make sure that the list of the method throws clause matches the list in Javadocs.

 // valid
 /**
  * ...
  * @throws IOException description
  */
 void createLogFile() throws IOException { ... }

 // invalid
 /**
  * ...
  * @throws IOException description
  */
 void createLogFile() { ... }

 // bad documentation
 /**
  * ...
  */
 void createLogFile() throws IOException { ... }

Consider the narrative style for your documentation. Instead of "A logfile will be created", you could say "Creates a logfile".

  • 发表于 2018-07-13 17:54
  • 阅读 ( 263 )
  • 分类:sof

条评论

请先 登录 后评论
不写代码的码农
小编

篇文章

作家榜 »

  1. 小编 文章
返回顶部
部分文章转自于网络,若有侵权请联系我们删除