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


<overview>
<p>
A public method or constructor that does not have a Javadoc comment makes an API more 
difficult to understand and maintain.
</p>

</overview>
<recommendation>

<p>
Public methods and constructors should be documented to make an API usable.
For the purpose of code maintainability, it is also advisable to document non-public
methods and constructors.
</p>
<p>
The Javadoc comment should describe <em>what</em> the method or constructor does
rather than <em>how</em>, to allow for any potential implementation change that is
invisible to users of an API. It should include the following:</p>
<ul>
  <li>A description of any preconditions or postconditions</li>
  <li>Javadoc tag elements that describe any parameters, return value, and thrown exceptions</li>
  <li>Any other important aspects such as side-effects and thread safety</li>
</ul>
<p>
Documentation for users of an API should be written using the standard Javadoc format.
This can be accessed conveniently by users of an API from within standard IDEs,
and can be transformed automatically into HTML format.
</p>

</recommendation>
<example>

<p>The following example shows a good Javadoc comment, which clearly explains what the method does, 
its parameter, return value, and thrown exception.</p>

<sample src="MissingJavadocMethods.java" />

</example>
<references>


<li>
  J. Bloch, <em>Effective Java (second edition)</em>, Item 44.
  Addison-Wesley, 2008.
</li>
<li>
Help - Eclipse Platform:
<a href="http://help.eclipse.org/indigo/topic/org.eclipse.jdt.doc.user/reference/preferences/java/compiler/ref-preferences-javadoc.htm">Java Compiler Javadoc Preferences</a>.
</li>
<li>
  Java SE Documentation:
  <a href="http://www.oracle.com/technetwork/java/javase/documentation/index-137868.html">How to Write Doc Comments for the Javadoc Tool</a>, 
  <a href="http://www.oracle.com/technetwork/java/javase/documentation/index-142372.html">Requirements for Writing Java API Specifications</a>.
</li>


</references>
</qhelp>
