Javadoc，在Eclipse中出现“未抛出异常”的问题

Question

当创建JavaODC时，您描述了方法可能引发的异常，对吗？

看一个示例：

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.");

    }
}

这是我针对该方法的Javadoc文档。

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

当我将代码导出为 javadoc 时，Eclipse 给出以下提示：

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

然而Eclipse希望我捕获那个异常。

为什么我的Eclipse会给出以上错误提示？

- Erwin Ivanov

---

@ernest_k Eclipse 给我相同的错误信息，带有 (@)throws。 - Erwin Ivanov

将异常添加到方法的“throws”子句中：public void createLogFile() throws IOException。 - ernest_k

消息是正确的。代码不会抛出异常 - 你可以使用try-catch来处理它。 - piradian

@ernest_k 你是什么意思？ - Erwin Ivanov

@piradian 我应该如何编写我的Javadoc呢？ - Erwin Ivanov

如果不抛出异常，则不应将其添加到javadoc中。 - piradian

Answer 1

当你编写一个方法时，实现方式对调用者来说是隐藏的（忽略你自己编写该方法时可以看到实现方式的事实）。有时在方法的实现中，你会遇到异常（或者甚至会抛出自定义异常）。有两件事情你可以做：

捕获

当你想要处理异常时，你可以捕获它。这意味着你知道一些可能会出错的事情，并且知道如何处理，以便程序在发生异常时可以继续以可预测的方式运行。

由于调用者无法看到你的实现方式，因此对他们来说它完全被隐藏了。

抛出

如果你不想处理异常，因为让调用者意识到问题并处理更加合适。在这种情况下，你不会捕获它，而是通过throws关键字将该Exception添加到方法中。当你这样做时，你可以在方法Javadoc中添加@throws或@exception注解，告诉调用者什么时候可以期望收到特定的异常。

由于该注解仅用于告诉调用者何时期望以及如何正确处理由方法抛出的异常，因此添加任何未被方法抛出的异常是没有意义的。

请注意，你只需要throws已检查异常。方法不需要通过throws列出未经检查的异常，因为它们通常是由编写不良的代码引起的。

- Jai

Answer 2

处理异常有两种方式：

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  {
      //...
   }
   

---

_{注意：标签@throws和@exception是同义词。参考}

- azro

---

那么如果我捕获了异常（就像在我的情况下），我不应该在我的javadoc中写任何东西吗？ - Erwin Ivanov

@ErwinIvanov 是的，完全正确。因为Javadoc提供了如何使用该方法的信息，并且因为此方法不会引发任何IOException，所以您不应编写它。 - azro

@ErwinIvanov 是的。@exception 注释与 ... throws SomethingException 一起使用。当您捕获异常时，您正在处理它。当您 throws 它时，您要求调用者处理它。 - Jai

Answer 3

该函数应该抛出您在javadoc注释中定义的异常。实际上，您并没有抛出IOException，而是捕获了它。

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.");

    }
}

- olgunyldz

---

当捕获异常时，我在我的javadoc中需要做些什么吗？ - Erwin Ivanov

你的代码似乎不可能，因为如果捕获了异常，它就不可能传播 ;) - azro

不需要在捕获时添加异常情况。 - olgunyldz

Answer 4

在Javadocs的@throws条款中不应包括IOException，因为您从未抛出它。

显然，Eclipse试图确保方法throws子句的列表与Javadocs中的列表匹配。

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

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

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

考虑文档的叙述风格。不要写成"A logfile will be created"，而应该写成"创建日志文件"。

- Andrew Tobilko