CSci 435/535: Homework 3

Implementation Tools #2

Due Friday, February 4th by 11am

Summary

This assignment is an introduction to Javadoc and JUnit.

Javadoc Comments

• Javadoc recognizes special comments  /** .... */ which are highlighted blue by default in Eclipse (regular comments // and /* ... */ are highlighted green).
• Javadoc allows you to attach descriptions to classes, constructors, fields, interfaces and methods in the generated html documentation by placing Javadoc comments directly before their declaration statements.  
• HTML tags are allowed in Javadoc comments.
• Here's an example using Javadoc comments to describe a class, a field and a constructor:
      

  /** Class Description of MyClass */
  public class MyClass
  {
  	/** Field Description of myIntField */
  	public int myIntField;
          /** Constructor Description of MyClass() */
  	public MyClass()
  	{
  		// Do something ...
  	}
  }

Javadoc Tags

• Tags are keywords recognized by Javadoc which define the type of information that follows.
• Tags come after the description (separated by a new line).
• Here are some common pre-defined tags:
  • @author [author name] - identifies author(s) of a class or interface.
  • @version [version] - version info of a class or interface.
  • @param [argument name] [argument description] - describes an argument of method or constructor.
  • @return [description of return] - describes data returned by method (unnecessary for constructors and void methods).
  • @exception [exception thrown] [exception description] - describes exception thrown by method.
  • @throws [exception thrown] [exception description] - same as @exception.
• Here's an example with tags:
  

  /** Description of MyClass 
   *
   * @author John Doe
   * @author Jane Doe
   * @version 6.0z Build 9000 Jan 3, 1970.
   */
  public class MyClass
  {
  	/** Description of myIntField */
  	public int myIntField;
  	/** Description of MyClass() 
  	 * 
  	 * @throws MyException 		Description of myException
  	 */
  	public MyClass() throws myException
  	{
  		// Blah Blah Blah...
  	}
  
  	/** Description of myMethod(int a, String b)
  	 * 
  	 * @param a			Description of a
  	 * @param b			Description of b
  	 * @return			Description of c
  	 */
  	public Object myMethod(int a, String b)
  	{
  		Object c;
  		// Blah Blah Blah...
  		return c;
  	}
  }

Javadoc in Eclipse

1. Download Student.java and TestStudent.java. Don't worry if TestStudent.java has errors right now.
2. Create a new project in Eclipse called <USER-NAME>-HW3 and import the two files into it. (File → Import → File System.)
3. Add Javadoc comments for all the attributes and methods of the Student class that are missing them. Also, add yourself as an author of the class.
4. Right-click on the project name and go to Export → Javadoc.
If you are in Windows, you will have to configure Eclipse to point to javadoc.exe in the bin directory of wherever you installed Java.
5. After you click Finish, a directory called doc will be created in the HW3 project that has the generated documentation files. Take a look at the Student.html file in the doc folder using a browser.
6. You can also use javadoc on the command line by running javadoc <FILE_NAME>

JUnit in Eclipse

1. The first thing you must to to use JUnit in Eclipse is to import junit.jar. Right-click on the project name, and choose Properties. In the tree on the left, select Java Build Path. Next, choose Add External JARs and browse to find junit.jar. If you are using Windows, it will be located in <eclipsedir>\plugins\org.junit_<version number>\junit.jar. On department machines, it is under /usr/local/eclipse/plugins/org.junit_3.8.1/junit.jar.
2. To create a test case, go to New → Other → Java → JUnit → Junit Test Case. You do not have to do this now because you have already been given a test case in TestStudent.java.
3. TestStudent is a subclass of TestCase, so it inherits a variety of testing assertions. These include assertEquals, assertTrue/False, assertSame/NotSame, and assertNull/NotNull. There is also a fail() method that just causes the current TestCase to fail.
4. To run the test case, right-click on TestStudent.java and go to Run → JUnit Test. There should be two failures. Why? In the Javadoc comments at the top of TestStudent.java, explain why there were failures.
5. Debug these failures so that the test cases pass. Do not change the test cases!
6. Save all your changes and then zip up the HW3 project. Go to File → Export → Zip File. If your username is txjeff, name your file txjeff-HW3.zip. E-mail your zip file to csci435@coppit.org.

Grading

75 points total