Writing Javadoc Comments for a Class

CS1

This assignment combines implementing a class definition (constructors, getters, setters for a Rectangle) with using Javadoc comments to document the class. This assignment includes background information on the Javadoc tool, including information about technical requirements (such as the @param tag) and style guidelines for javadocs (guidelines nicely summarized on Oracle's website). The rubric includes separate items for both the technical part of the assignment (writing the class) and the Javadoc part of the assignment. This could be easily modified to incorporate Javadocs with some other programming assignment.

This assignment assumes that students are able to implement a basic class definition in Java, with constructors, getters, and setters.

Norm Krumpe

Javadocs

One Week

Writing

Class creation, documentation

Organizations write code that must be sufficiently documented in order for other team members (current and future) to use that code. Often, such documentation must be written using a given set of requirements (as defined by an employer or by some broader community).

In this assignment, you will be writing code, along with the documentation for that code. There are two kinds of standards for that documentation:

1. Technical standards: the documentation you write needs to be parsable by a piece of software that turns your comments into a web page. The Javadoc standards are documented on Oracle's web page, "How to Write Doc Comments for the Javadoc Tool"
2. Human standards: the documentation you write needs to be written in a grammatic style that is consistent with how others write similar documentation. The community style for these standards is documented on the same Oracle web page, in the "Style Guide" section.

N/A