<!DOCTYPE qhelp PUBLIC
  "-//Semmle//qhelp//EN"
  "qhelp.dtd">
<qhelp>


<overview>
<p>
A Javadoc <code>@throws</code> or <code>@exception</code> tag that references an exception
that cannot be thrown is misleading.
</p>

</overview>
<recommendation>

<p>
Ensure that you only include the <code>@throws</code> or <code>@exception</code> tags in Javadoc 
when an exception can be thrown.
</p>

</recommendation>
<example>

<p>The following example shows a method with Javadoc that claims it can throw 
<code>Exception</code>. Since <code>Exception</code> is a checked exception and the method 
does not declare that it may throw an exception, the Javadoc is wrong and should be updated.</p>

<sample src="ImpossibleJavadocThrows.java" />

<p>In the following example the Javadoc has been corrected by removing the <code>@throws</code>
tag.</p>

<sample src="ImpossibleJavadocThrowsFix.java" />

</example>
<references>


<li>
  Java SE Documentation:
  <a href="https://www.oracle.com/technical-resources/articles/java/javadoc-tool.html#throwstag">How to Write Doc Comments for the Javadoc Tool</a>, 
</li>


</references>
</qhelp>
