116 lines
4.2 KiB
HTML
116 lines
4.2 KiB
HTML
<!DOCTYPE HTML PUBLIC "-//IETF//DTD HTML//EN">
|
|
<html>
|
|
<head>
|
|
<title>Checks for Javadoc Comments</title>
|
|
<link rel="stylesheet" type="text/css" href="mystyle.css">
|
|
</head>
|
|
|
|
<body>
|
|
<h1>Checks for Javadoc Comments</h1>
|
|
|
|
<p>Checkstyle will check that the following constructs have a Javadoc comment:</p>
|
|
<ul>
|
|
<li>class</li>
|
|
<li>interface</li>
|
|
<li>variable</li>
|
|
<li>method</li>
|
|
</ul>
|
|
|
|
<p>The property <span class="code">checkstyle.javadoc.scope</span> controls
|
|
the visibility scope where Javadoc comments are checked. The property type is
|
|
<a href="property_types.html#scope">scope</a> and defaults to
|
|
<span class="default">private</span>.</p>
|
|
|
|
<p>For example, you can check Javadoc comments only for <span
|
|
class="code">public</span> and <span class="code">protected</span> definitions
|
|
by setting the property to <span class="default">protected</span>. Scoping
|
|
rules apply, so a <span class="code">public</span> method in a package visible
|
|
class is not checked.</p>
|
|
|
|
|
|
<h2>package.html check</h2>
|
|
|
|
<p>The property <span class="code">checkstyle.require.packagehtml</span>
|
|
controls whether to require that a <span class="code">package.html</span> file
|
|
exists for each package. The property type is
|
|
<a href="property_types.html#boolean">boolean</a> and defaults to
|
|
<span class="default">false</span>.</p>
|
|
|
|
|
|
<h2>Class/Interface Javadoc checks</h2>
|
|
|
|
<p>The property <span class="code">checkstyle.require.version</span> controls
|
|
whether to require an <span class="default">@version</span> tag to be defined
|
|
for class and interface Javadoc comments. The property type is
|
|
<a href="property_types.html#boolean">boolean</a> and defaults to
|
|
<span class="default">false</span>.</p>
|
|
|
|
<p>The property <span class="code">checkstyle.allow.noauthor</span> controls
|
|
whether to allow no <span class="default">@author</span> tag to be defined for
|
|
class and interface Javadoc comments. The property type is
|
|
<a href="property_types.html#boolean">boolean</a> and defaults to
|
|
<span class="default">false</span>.</p>
|
|
|
|
|
|
<h2>Method Javadoc checks</h2>
|
|
|
|
<p>Javadoc comments for methods are checked to ensure that the following tags exist (if required):</p>
|
|
<ul>
|
|
<li><span class="code">@return</span></li>
|
|
<li><span class="code">@param</span></li>
|
|
<li><span class="code">@throws</span> or <span class="code">@exception</span></li>
|
|
<li><span class="code">@see</span></li>
|
|
</ul>
|
|
|
|
<p>For example the following is valid:</p>
|
|
<pre>
|
|
/**
|
|
* Checks for a return tag.
|
|
* @return the index of the next unchecked tag
|
|
* @param aTagIndex the index to start in the tags
|
|
* @param aTags the tags to check
|
|
* @param aLineNo the line number of the expected tag
|
|
**/
|
|
public int checkReturnTag(final int aTagIndex,
|
|
JavadocTag[] aTags,
|
|
int aLineNo)
|
|
</pre>
|
|
|
|
<p>The property <span class="code">checkstyle.javadoc.checkUnusedThrows</span>
|
|
controls whether to check if an undocumented exception is a subclass of
|
|
<span class="code">java.lang.RuntimeException</span>. The property type is
|
|
<a href="property_types.html#boolean">boolean</a> and defaults to
|
|
<span class="default">false</span>.</p>
|
|
|
|
<p>This supports the convention in
|
|
the <a href="http://java.sun.com/j2se/javadoc/writingdoccomments/index.html#throwstag">Sun Javadoc Guidelines</a>
|
|
and the "Effective Java" book.</p>
|
|
|
|
<p>The classpath may need to be configured to locate the class
|
|
information. The classpath configuration is dependent on the mechanism used to
|
|
invoke Checkstyle.</p>
|
|
|
|
<div class="tip">
|
|
<h4 class="tip">Tip</h4>
|
|
|
|
<p>It can be extremely painful writing or duplicating Javadoc for a method
|
|
required for an interface. Hence checkstyle supports using the convention of
|
|
using a single <span class="code">@see</span> tag instead of all the other
|
|
tags. For example, if the previous method was implementing a method required
|
|
by the <span class="code">com.puppycrawl.tools.checkstyle.Verifier</span>
|
|
interface, then the Javadoc could be done as:</p>
|
|
|
|
<pre>
|
|
/** @see com.puppycrawl.tools.checkstyle.Verifier **/
|
|
public int checkReturnTag(final int aTagIndex,
|
|
JavadocTag[] aTags,
|
|
int aLineNo)
|
|
</pre>
|
|
</div>
|
|
|
|
<hr>
|
|
<p align="center">Copyright © 2002 Oliver Burn. All rights Reserved.</p>
|
|
|
|
</body>
|
|
</html>
|