mirror of
https://github.com/github/codeql.git
synced 2026-04-17 13:04:02 +02:00
e21cbe82a9
Where possible update Java documentation links to Java 11. Additionally update some other links to use HTTPS.
65 lines
2.0 KiB
XML
65 lines
2.0 KiB
XML
<!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="https://help.eclipse.org/2020-12/advanced/content.jsp?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="https://www.oracle.com/technical-resources/articles/java/javadoc-tool.html">How to Write Doc Comments for the Javadoc Tool</a>,
|
|
<a href="https://www.oracle.com/java/technologies/javase/api-specifications.html">Requirements for Writing Java API Specifications</a>.
|
|
</li>
|
|
|
|
|
|
</references>
|
|
</qhelp>
|