Javadocs
Now that we have created a Window class, we should create an API for our class to tell users of our class how to use it.
The JDK comes with a tool called Javadoc that can create APIs from any Java class that is commented using a specific format. That format is known as Javadoc comments, or Doc comments. We will study this format in more detail in a future lesson, but for now here's the format you need to use:
/**
This is a Javadoc comment. The text you write here will be displayed as the summary text
for whatever element (class header, method header, attribute) directly follows this comment.
If what follows this comment is a void method or constructor then you also need to supply
a description for each parameter in the format shown below:
@param param1_name Description
@param param2_name Description
@param param3_name Description
...
*/
The first Javadoc comment you should write is a class summary that describes the purpose and usage of your class. Since Javadoc comments always describe whatever element is directly below them, you should put this summary comment immediately above the class declaration.
/**
This class describes a four-pane window capable of changing its location, dimensions, and colors.
The colors are separated into two types: one color for the outline of the window (the frame) and
one color for the interior panels. In order to create a Window, you must supply a location (x, y)
where the window will be centered along with a DrawingTool that will be used to draw the Window.
The default values for a window are
- position set in constructor
- width and height are 100
- frame color is black
- panel color is yellow
Example usage:
SketchPad paper = new SketchPad(600, 400);
DrawingTool pen = new DrawingTool();
Window win = new Window(200, 50, pen);
win.setFrameColor(Color.BLUE);
win.draw();
*/
public class Window { // Class summary goes ABOVE this line
// Attributes
...same as before
// Constructors
...same as before
// Methods
...same as before
}
After the class summary, you should write a Javadoc comment above each attribute explaining its purpose.
/**
class summary goes here
*/
public class Window {
// Attributes
/** x-position where the window will be centered */
int xPos;
/** y-position where the window will be centered */
int yPos;
/** horizontal width of the window in pixels */
int width;
/** vertical height of the window in pixels */
int height;
/** color of the outer frame, include the crossbars */
Color frameColor;
/** color of the four interior window panels */
Color interiorColor;
/** a DrawingTool object to use for drawing this window */
DrawingTool pencil;
// Constructors
...same as before
// Methods
...same as before
}
After commenting the attributes, you should write a Javadoc comment above each constructor you have.
/**
class summary...
*/
public class Window {
// Attributes
...same as before
// Constructors
/**
This constructor creates a window centered at (x, y) using the DrawingTool passed in.
The default values for a new Window created by this constructor are:
- width and height are 100
- frame color is black
- panel color is yellow
@param x The new x-coordinate of the window's center
@param y The new y-coordinate of the window's center
@param d The DrawingTool used to draw this window
*/
public Window(int x, int y, DrawingTool d) {
...same as before
}
// Methods
...same as before
}
Finally, write a Javadoc comment above each method. If the method has parameters, include an @param tag for each parameter as shown in the second method below.
/**
class summary...
*/
public class Window {
// Attributes
...same as before
// Constructors
...same as before
// Methods
/**
This method draws a window with the properties specified by each attribute.
*/
public void draw() {
...same as before
}
// Setter Methods
/**
This method updates the center location (x, y) of the window. Note that if a window
has already been drawn, it will not move to this new location. Old windows drawn
will stay on the screen where they are. However, you can use this method followed
by draw() to draw another copy of this window in the new location.
@param x The new x-coordinate of the window's center
@param y The new y-coordinate of the window's center
*/
public void setPosition(int x, int y) {
...same as before
}
...same idea for the remaining methods
}
Adding line breaks
Since a Javadoc API is an HTML web page, all whitespace is ignored. This means that any attempt at line breaks and whitespace formatting is ignored.
If you type the following, instead of seeing what you might expect:
/**
If this is your Javadoc comment and it has intentional white space, formatting, or line breaks such as
this
or this
or this bullet list:
- width and height are 100
- frame color is black
- panel color is yellow
then ALL WHITESPACE and line breaks (enter key) will be treated as a single space.
*/
You will actually see this block of text:
/** If this is your Javadoc comment and it has intentional white space, formatting, or line breaks such as this or this or this bullet list: - width and height are 100 - frame color is black - panel color is yellow then ALL WHITESPACE and line breaks (enter key) will be treated as a single space. */
In order to hardcode a line break (enter key), you can use the HTML tag <br> in your Javadoc comment. For example, if this is your Javadoc comment:
/**
If this is your Javadoc comment and it has intentional white space, formatting, or line breaks such as <br>
<br>
this <br>
or this <br>
<br>
or this bullet list:<br>
<br>
- width and height are 100<br>
- frame color is black<br>
- panel color is yellow<br>
<br>
then ALL WHITESPACE and line breaks (enter key) will be treated as a single space.
*/
Then, there will be a line break at each <br>, and it will appear like this:
/**
If this is your Javadoc comment and it has intentional white space, formatting, or line breaks such as
this
or this
or this bullet list:
- width and height are 100
- frame color is black
- panel color is yellow
then ALL WHITESPACE and line breaks (enter key) will be treated as a single space.
*/
A second or alternate solution is to use the HTML preformatted tag <PRE> </PRE> which displays everything between the tags in a monspaced font EXACTLY as you wrote it.
/**
The formatting below will be displaed exactly as you typed it.
<PRE>
Hello
there
- width and height are 100
- frame color is black
- panel color is yellow
</PRE>
then ALL WHITESPACE and line breaks (enter key) will be treated as a single space.
*/
Tino APCS