The third milestone for the team project is design documentation,
which shall include:
- Class diagram for your module
- Javadoc for your module's API
- Sequence diagrams for your module's use cases
The centerpiece of a design document is the class diagram, which should
show:
- All of the types (classes and interfaces) involved in your
module, including bean classes, and their relationships
- All object properties for both managed and unmanaged
beans
- All methods in each class's applications programming
interface (API)
Exact type signatures for the methods need not be given, since they
will be shown later.
See the example for the
User Management module.
The standard method for presenting API documentation for Java classes
is through
Javadoc.
Here we describe Javadoc guidelines, NetBeans support for
Javadoc, and how to document packages.
For each of the types that you define in your class diagram, create a
source file that declares the class or interface and each public
method:
- The class or interface declaration must be preceded by a comprehensive
Javadoc comment describing the high-level purpose of the class
or interface
- Public method parameters, parameter types, and return types must be
given
- Method bodies can be empty, except to keep NetBeans happy
non-void methods must put in dummy return values.
- For example, if a method returns a String value,
then its body should consist of, for example,
{ return ""; }
- Note: method bodies don't have to be empty
— if your methods have code at this time all the
better. However, they must compile.
- Each method must be well described with a Javadoc comment
- Each method parameter and return type should have an
appropriate Javadoc keyword (that
is, @param, @return) and value.
NetBeans makes it easy to document methods:
- After writing your (possibly empty) method declaration,
open a new line before the declaration,
type /**, and press Enter
- NetBeans will insert a Javadoc comment template for the
method with appropriate keywords
To observe your documentation in a browser, right-click
the
Environmental_Simulation project node and
select
Generate Javadoc.
For an example see the
Current Javadoc for the project,
and the
userman module in particular.
Good API documentation also describes the
packages containing
class and interface types.
To document your packages, simply include a
package.html file in
your source package.
Here is the
package.html file for the
userman package:
You will create sequence diagrams that demonstrate how the instances
of your classes will collaborate to accomplish your module's use
cases from your
analysis document.
You should cover all your use cases and their variations, although
you may combine them into one sequence diagram if feasible (see the
example following).
Note: If you find yourself changing or adding to your original
use cases, that is fine — but be sure to
update your analysis document accordingly.
The following example takes a use case and its variations from
the
User Management module.
- The user clicks the Login option on welcome page
- The application presents the login page
- The user enters a user name and a password and clicks
the Login button
- The application presents the
project task page, greeting the user by name
Variation 1. Name Not Found
- Start at step 3
- The application redisplays the login page with the message
"That user name is not registered"
Variation 2. Password Not Matched
- Start at step 3
- The application redisplays the login page with the message
"That password does not match"
Your Javadoc API documentation will be submitted simply by committing
the affected
.java files to the project repository.
For your class and sequence diagrams:
- Render each diagram in a standard image format
- Create a folder named team_n_design, where
where n is your team number
- Place each image file in this folder
- Include a README file that correlates sequence
diagrams with use cases (alternatively, you can include this
information in diagram notes)
Zip your
team_n_design folder and submit it using
Web Drop.
