mirror of
https://github.com/github/codeql.git
synced 2026-04-28 02:05:14 +02:00
43 lines
1.4 KiB
XML
43 lines
1.4 KiB
XML
<!DOCTYPE qhelp PUBLIC
|
|
"-//Semmle//qhelp//EN"
|
|
"qhelp.dtd">
|
|
<qhelp>
|
|
|
|
|
|
<overview>
|
|
<p>
|
|
Javadoc comments for public methods, constructors and generic classes should use the <code>@param</code> tag to describe the available
|
|
parameters and type parameters. If the comment includes any empty, incorrect or outdated parameter names then this will make
|
|
the documentation more difficult to read.
|
|
</p>
|
|
|
|
</overview>
|
|
<recommendation>
|
|
|
|
<p>The Javadoc comment for a method, constructor or generic class should always use non-empty <code>@param</code> values that match actual parameter or type parameter names.</p>
|
|
|
|
</recommendation>
|
|
<example>
|
|
|
|
<p>The following example shows good and bad Javadoc comments that use the <code>@param</code> tag.</p>
|
|
|
|
<sample src="SpuriousJavadocParam.java" />
|
|
|
|
</example>
|
|
<references>
|
|
|
|
|
|
<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#@param">How to Write Doc Comments for the Javadoc Tool</a>,
|
|
<a href="https://docs.oracle.com/en/java/javase/11/docs/specs/doc-comment-spec.html#param">Documentation Comment Specification for the Standard Doclet</a>
|
|
</li>
|
|
|
|
|
|
</references>
|
|
</qhelp>
|