Welcome to Lesson 18!


Learning Objectives
By the end of today's class, you should know...
  • How do you write a Javadoc comment
  • What is a tag?
  • List some of the common tags

Announcements

  • Midterm 2 after a short lesson and the break!
  • Don't forget Lab 9 (due Friday!) and Assignment 17 (due Tuesday)

Javadoc Comments
  • Java also has a type of comment known as a Javadoc comment
  • Javadoc comments are used to generate documentation automatically
  • Syntax: 
    /**
 * Description part of a Javadoc comment
 *
 * @tag Comment for the tag
 */
  • Note the extra star (*) in the opening of the comment
  • Javadoc comments have two parts:
    1. Description of the code
    2. Followed by zero or more tags
  • For example, you should put a Javadoc comment like the following at the beginning of every class: 
    /**
 * Hello.java
 * Purpose: Prints a message to the screen.
 *
 * @author Jennifer Parrish
 * @version 1.4 6/2/16
 */
  • In this example, we have two tags:
    • @author followed by the name of the author
    • @version followed by the version number or date

Commenting Methods
  • In addition, you put Javadoc comments like the following before every method: 
    /**
 * The main method for the Hello program.
 * @param args Not used
 */
  • Then you use a tool, known as Javadoc, to automatically create program documentation
  • Also, a tool known as CheckStyle will check your comments (among other things) for correct usage
  • For your homework, every method must have a Javadoc comment.
  • Comments are for human readers, not compilers
  • Your comments should be structured as follows
    1. Method comments start with /** and ends with */
    2. The first line explains the idea of the method, not the implementation
    3. An @param entry explains each parameter - one for each parameter in the method
    4. An @return entry describes the return value (not required for void methods)
  • The following example has two fully commented methods:

    /**
     * multiplies a number by itself
     * @param number the number to square
     * @return the squared number
     */

    public static double square(double number) {
        double result = number * number;
        return result;
    }
    
    /**
     * Formats a date into the month/day/year format
     * @param month the current month
     * @param day the current day
     * @param year the current year
     * @return the formatted date
     */

    public static String printDate(int month, int day, int year) {
        return "" + month + "/" + day + "/" + year;
    }

    public static void main(String[] args) {
        //method calls here
    }

  • Note that if you type /** above a method, Eclipse will help you fill in the rest.

More Information

Activity 18.1: JavaDoc Comments (10 pts)

  • Open up a Java file in Eclipse called Comments.java in a project named Comments
  • Copy and paste the below starter code into your program.
  • Add a proper javadoc comment for each method in the program.
  • When you are finished, submit your program to Canvas.
/**
 *
 * @author
 *
 */

public class Comments {
   
    public static boolean isLeapYear(int date) {
        if (date % 4 == 0) {
            return true;
        } else {
            return false;
        }
    }
   
    public static String formatName(String first, char initial, String last) {
        return first + " " + initial + ". " + last;
    }
   
    public static double areaCircle(double radius) {
        return Math.PI * radius * radius;
    }
       
    public static void main(String[] args) {
        //method calls go here
    }
}


Upcoming Assignments