AppPerfect

Java Documentation JavaDoc

Rules available in this category:

1. Missing_return_tag
2. Always_mention_if_method_returns_null_or_not
3. Always_provide_javadoc_for_to_string_method
4. Enforce_custom_Javadoc_tags_for_public_fields
5. Enforce_custom_Javadoc_tags_for_public_types
6. Remove_unused_method_javadoc_tags
7. Avoid_using_return_tag_if_return_type_is_void
8. Missing_param_tag
9. Missing_author_tag
10. Missing_concurrency_tag
11. Missing_javadoc_for_public_methods
12. Always_use_throws_or_exception_Javadoc_tag_in_private_methods
13. Always_use_throws_or_exception_Javadoc_tag_in_public_methods
14. Always_use_throws_or_exception_Javadoc_tag_in_protected_methods
15. Always_use_throws_or_exception_Javadoc_tag_in_package_private_methods
16. Missing_javadoc_for_fields
17. Missing_javadoc_for_classes
18. Missing_version_tag

Rule 1: Missing_return_tag

Severity:  Medium
Rule:  Use javadoc return tag for better readability
Reason:  Use javadoc return tag for better readability

Usage Example: 

package com.rule;

class Missing_return_tag_violation
{
	int getSize()
	{
		return 0;
	}
}

Should be written as:

package com.rule;

class Missing_return_tag_correction
{
	/**
	 * @return Returns the size
	 */
	int getSize()
	{
		return 0;
	}
}

Reference:  No Reference Available.

Rule 2: Always_mention_if_method_returns_null_or_not

Severity:  Low
Rule:  By mentioning if a method returns null or not, the invokers can know whether they would need to check the return value before using it.
Reason:  By mentioning if a method returns null or not, the invokers can know whether they would need to check the return value before using it.

Usage Example: 

public class Test
{
 /**
  * method getValue  // VIOLATION
  */
 private String getValue(int i) 
{
  String s = null;
  if (i < 0) 
	 {
return "s";
  }
  return s;
 }
}

Should be written as:

public class Test
{
 /**
  * method getValue
  * 
  * @return the String "s", or <code>null</code> if the number passed  // FIXED 
  *in is >= 0
  */
 private String getValue(int i) 
{
  String s = null;
  if (i < 0) 
	 {
return "s";
  }
  return s;
 }
}

Reference:  Not available.

Rule 3: Always_provide_javadoc_for_to_string_method

Severity:  Low
Rule:  By documenting the toString method, it would tell the user how the data will be formatted.
Reason:  By documenting the toString method, it would tell the user how the data will be formatted.

Usage Example: 

public class Test 
{
 public Test () 
{
  _name = "AppPerfect";
  _product = "CA";
 }
 
  public String toString ()  // VIOLATION
 {
  return "name=" + _name + ", product=" + _product;
 }
 
 private String _name;
 private String _product;
}

Should be written as:

public class Test 
{
 public Test () 
{
  _name = "AppPerfect";
  _product = "CA";
 }

// FIXED
 /**
  * The string representation is "name=NAME, product=PRODUCT"
  * Where NAME is the company name and PRODUCT is the product name.
  */
  public String toString ()
 {
  return "name=" + _name + ", product=" + _product;
 }
 
 private String _name;
 private String _product;
}

Reference: 

Rule 4: Enforce_custom_Javadoc_tags_for_public_fields

Severity:  Low
Rule:  Using custom tags help provide further details to the javadoc thereby improves the readability.
Reason:  Using custom tags help provide further details to the javadoc thereby improves the readability.

Usage Example: 

public class Test
{
/**
 * i
 */
 public int i ; // VIOLATION
 
}

Should be written as:

public class Test
{
/**
 * i
 * @since 1.0
 */
 public int i ; // FIXED
 
}

Reference:  Not Available.

Rule 5: Enforce_custom_Javadoc_tags_for_public_types

Severity:  Low
Rule:  Using custom tags help provide further details to the javadoc thereby improves the readability.
Reason:  Using custom tags help provide further details to the javadoc thereby improves the readability.

Usage Example: 

/**
 * Class Test
 */
public class Test // VIOLATION
{ 
}

Should be written as:

/**
 * Class Test
 * @since v1.0
 */
public class Test // FIXED
{
}

Reference:  Not Available.

Rule 6: Remove_unused_method_javadoc_tags

Severity:  Medium
Rule:  Leaving unused Javadoc tags in methods can lead to confusion.
Reason:  Leaving unused Javadoc tags in methods can lead to confusion.

Usage Example: 

public class Test 
{

 /**
  * @param id1 
  * @return int
  */ 					// VIOLATION 
 public void setId (String id) 
{
  _id = id;
 }
 private String _id;
}

Should be written as:

Change '@param id1' to @param id.
Remove '@return int'.

package examples.rules.javadoc;

public class Test
{

 /** 
  * @param id is set as the new id.
  */  					// FIXED
 public void setId (String id) 
{
  _id = id;
 }
 private String _id;
}

Reference:  No references available

Rule 7: Avoid_using_return_tag_if_return_type_is_void

Severity:  Medium
Rule:  It might lead to confusion.
Reason:  It might lead to confusion.

Usage Example: 

public class MyClass
{

 /**
  * Displays text to the screen
  * @return ...
  */
 public void display ()  // VIOLATION
 {
  System.out.println ("hello");
 }

}

Should be written as:

public class MyClass
{

 /**
  * Displays text to the screen  
  */
 public void display () // CORRECTION
 {
  System.out.println ("hello");
 }

}

Reference:  No references available.

Rule 8: Missing_param_tag

Severity:  Medium
Rule:  Provide @param tag in the Java doc.
Reason:  Provide @param tag in the Java doc.

Usage Example: 

package com.rule;
/**
* This class is used to demo Missing_param_tag rule.
* @author name.
* @version 1.0
*/
class Missing_param_tag_violation
{
	/**
	* Method methodX.
	*/
	public void methodX(int i)		// VIOLATION
	{
		//...
	}
}

Should be written as:

package com.rule;
/**
* This class is used to demo Missing_param_tag rule.
* @author name.
* @version 1.0
*/
class Missing_param_tag_correction
{
	/**
	* Method methodX.
	* @param i
	*/
	public void methodX(int i)		// CORRECTION
	{
		//...
	}
}

Reference:  No Reference Available.

Rule 9: Missing_author_tag

Severity:  Medium
Rule:  Provide @author tag in the Java doc.
Reason:  Provide @author tag in the Java doc.

Usage Example: 

package com.rule;
/**
* This class is used to demo Missing_author_tag rule.	// VIOLATION
*/
class Missing_author_tag_violation
{
//...
}

Should be written as:

package com.rule;

/**
* This class is used to demo Missing_author_tag rule.
* @author name											// CORRECTION
* @version 1.0
*/
class Missing_author_tag_correction
{
//...
}

Reference:  Reference Not Available.

Rule 10: Missing_concurrency_tag

Severity:  Medium
Rule:  Provide @concurrency tag in the Java doc.
Reason:  Provide @concurrency tag in the Java doc.

Usage Example: 

public class Test
{
  
 public synchronized void method ()  // VIOLATION
 {
 }
}

Should be written as:

public class Test 
{
 /**
  *  Thread safety is maintained because this method doesn't do anything
  *  @concurrency ...
  */
 public synchronized void method ()  // FIXED
 {
 }
}

Reference:  Joshua Bloch: "Effective Java - Programming Language Guide"

Rule 11: Missing_javadoc_for_public_methods

Severity:  Medium
Rule:  Define java doc for public methods
Reason:  Define java doc for public methods

Usage Example: 

package com.rule;
/**
* This class is used to demo Missing_javadoc_for_public_methods rule.
* @author name.
* @version 1.0
*/
class Missing_javadoc_for_public_methods_violation
{
public void methodX()		// VIOLATION
{
//...
}
}

Should be written as:

package com.rule;
/**
* This class is used to demo Missing_javadoc_for_public_methods rule.
* @author name.
* @version 1.0
*/
class Missing_javadoc_for_public_methods_correction
{
/**
	* Method methodX.
	*/
public void methodX()		// CORRECTION
{
//...
}
}

Reference:  Reference Not Available.

Rule 12: Always_use_throws_or_exception_Javadoc_tag_in_private_methods

Severity:  Medium
Rule:  A description of the exceptions thrown by a method comprises an important part of the documentation required to use the method properly.
Reason:  A description of the exceptions thrown by a method comprises an important part of the documentation required to use the method properly.

Usage Example: 

import java.io.*;

public class MyClass
{
 /**
  * method()
  */
 private void method () throws IOException  // VIOLATION
 {
  System.in.read ();
 }
}

Should be written as:

import java.io.*;

public class MyClass
{
 /**
  * @throws IOException
  */
 private void method () throws IOException  // FIXED
 {
  System.in.read ();
 }
}

Reference:  Joshua Bloch: "Effective Java - Programming Language Guide"
Joshua Bloch: "Effective Java - Programming Language Guide"

Rule 13: Always_use_throws_or_exception_Javadoc_tag_in_public_methods

Severity:  Medium
Rule:  A description of the exceptions thrown by a method comprises an important part of the documentation required to use the method properly.
Reason:  A description of the exceptions thrown by a method comprises an important part of the documentation required to use the method properly.

Usage Example: 

import java.io.*;

public class MyClass
{
 /**
  * method()
  */
 public void method () throws IOException  // VIOLATION
 {
  System.in.read ();
 }
}

Should be written as:

import java.io.*;

public class MyClass
{
 /**
  * @throws IOException
  */
 public void method () throws IOException  // FIXED
 {
  System.in.read ();
 }
}

Reference:  Joshua Bloch: "Effective Java - Programming Language Guide"

Rule 14: Always_use_throws_or_exception_Javadoc_tag_in_protected_methods

Severity:  Medium
Rule:  A description of the exceptions thrown by a method comprises an important part of the documentation required to use the method properly.
Reason:  A description of the exceptions thrown by a method comprises an important part of the documentation required to use the method properly.

Usage Example: 

import java.io.*;

public class MyClass
{
 /**
  * method()
  */
 protected void method () throws IOException  // VIOLATION
 {
  System.in.read ();
 }
}

Should be written as:

import java.io.*;

public class MyClass
{
 /**
  * @throws IOException
  */
 protected void method () throws IOException  // FIXED
 {
  System.in.read ();
 }
}

Reference:  Joshua Bloch: "Effective Java - Programming Language Guide"
Joshua Bloch: "Effective Java - Programming Language Guide"
Joshua Bloch: "Effective Java - Programming Language Guide"

Rule 15: Always_use_throws_or_exception_Javadoc_tag_in_package_private_methods

Severity:  Medium
Rule:  A description of the exceptions thrown by a method comprises an important part of the documentation required to use the method properly.
Reason:  A description of the exceptions thrown by a method comprises an important part of the documentation required to use the method properly.

Usage Example: 

import java.io.*;

public class MyClass
{
 /**
  * method()
  */
 void method () throws IOException  // VIOLATION
 {
  System.in.read ();
 }
}

Should be written as:

import java.io.*;

public class MyClass
{
 /**
  * @throws IOException
  */
 void method () throws IOException  // FIXED
 {
  System.in.read ();
 }
}

Reference:  Joshua Bloch: "Effective Java - Programming Language Guide"
Joshua Bloch: "Effective Java - Programming Language Guide"
Joshua Bloch: "Effective Java - Programming Language Guide"

Rule 16: Missing_javadoc_for_fields

Severity:  Medium
Rule:  Define java doc for fields
Reason:  Define java doc for fields

Usage Example: 

package com.rule;
/**
* This class is used to demo Missing_javadoc_for_fields rule.
* @author name.
* @version 1.0
*/
class Missing_javadoc_for_fields_violation
{
 	public  int field =9;		// VIOLATION
 }

Should be written as:

package com.rule;
/**
* This class is used to demo Missing_javadoc_for_fields rule.
* @author name.
* @version 1.0
*/
class Missing_javadoc_for_fields_Correction
{
/**
* a field which is used for...
*/
public int field =9;

Reference: 

Rule 17: Missing_javadoc_for_classes

Severity:  Medium
Rule:  Define java doc for all classes
Reason:  Define java doc for all classes

Usage Example: 

package com.rule;

class Missing_javadoc_for_classes_violation		// VIOLATION
{
//...
}

Should be written as:

package com.rule;
/**
* This class is used to demo Missing_javadoc_for_classes rule.		// CORRECTION
* @author name.
* @version 1.0
*/
class Missing_javadoc_for_classes_correction
{
//...
}

Reference:  Reference Not Available.

Rule 18: Missing_version_tag

Severity:  Medium
Rule:  Provide @version tag in the Java doc.
Reason:  Provide @version tag in the Java doc.

Usage Example: 

package com.rule;
/**
* This class is used to demo Missing_version_tag rule.
* @author name.
*/
class Missing_version_tag_violation			// VIOLATION
{
//...
}

Should be written as:

package com.rule;
/**
* This class is used to demo Missing_version_tag rule.
* @author name.
* @version 1.0
*/
class Missing_version_tag_correction		// CORRECTION
{
//...
}

Reference:  Reference Not Available.