Welcome to Lesson 17!


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

Announcements

  • Midterm 2 after a short lesson and the break
  • Next Quiz one week from today
  • No Lab this Friday due to holiday!
  • But, there is homework for Monday!


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
    4. An @return entry describes the return value
  • 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;
    }
    /**
     * Prints a date in the month/day/year format
     * @param month the current month
     * @param day the current day
     * @param year the current year
     */

    public static void printDate(int month, int day, int year) {
        System.out.println("The date: " + month + "/" + day + "/" + year);
        return;
    }

    //Write your methods here
    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 17.1: JavaDoc Comments (10 pts)
  • Open up a text editor and create a new file named comments.txt.
  • In the file, write the Javadoc comments for the following method.
public static double areaTriangle(double base, double height) {
    double area = 0.5 * base * height;
    return area;
}

public static String myName(String firstName, char initial, String lastName) {
    String fullName = firstName + " " + initial + ". " + lastName;
    return fullName;
}

public static boolean isLeapYear(int year) {
    if (year % 4 == 0) {
        return true;
    } else {
        return false;
    }
}
  • When you are finished, submit your comments.txt to Canvas.




Wrap Up
  • With your partner, answer the questions from today's learning objectives

Upcoming Assignments