Advanced Object-oriented Programming Lecture 11cgi.csc.liv.ac.uk/~akridel/COMP213-Fall2016/Lecture...private Vector myCars;...} which directs the compiler to look at all
Post on 02-Aug-2020
2 Views
Preview:
Transcript
COMP 213Advanced Object-oriented Programming
Lecture 11
Documentation and Javadoc.
Using Off-the-shelf Classes
• All Java classes are contained in some package.The default package is a directory:E.g., when compiling the file Main.java, the compiler will find a reference to class ArrayUnsortedList, so it will look for the file ArrayUnsortedList.class in the same directory (if it doesn’t find it, it will look for the file ArrayUnsortedList.java, and compile that).
• Classes from other packages (i.e., not in the current working directory) need to be explicitly imported.
Using Off-the-shelf Classes
• All Java classes are contained in some package.The default package is a directory:E.g., when compiling the file Main.java, the compiler will find a reference to class ArrayUnsortedList, so it will look for the file ArrayUnsortedList.class in the same directory (if it doesn’t find it, it will look for the file ArrayUnsortedList.java, and compile that).
• Classes from other packages (i.e., not in the current working directory) need to be explicitly imported.
Using Off-the-shelf Classes
• All Java classes are contained in some package.The default package is a directory:E.g., when compiling the file Main.java, the compiler will find a reference to class ArrayUnsortedList, so it will look for the file ArrayUnsortedList.class in the same directory (if it doesn’t find it, it will look for the file ArrayUnsortedList.java, and compile that).
• Classes from other packages (i.e., not in the current working directory) need to be explicitly imported.
Importing Classes
For example, to use the class Vector from package java.util, we write:
import java.util.Vector;
public class CarMain {
private Vector<Car> myCars;
...
}
Importing Classes
For example, to use the class Vector from package java.util, we write:
import java.util.Vector;
public class CarMain {
private Vector<Car> myCars;
...
}
Importing Classes
For example, to use the class Vector from package java.util, we write:
import java.util.Vector;
public class CarMain {
private Vector<Car> myCars;
...
}
Then the compiler knows where to look when it finds the name ‘Vector’.
Importing Classes
For example, to use the class Vector from package java.util, we write:
import java.util.Vector;
public class CarMain {
private Vector<Car> myCars;
...
}
Then the compiler knows where to look when it finds the name ‘Vector’.
Importing Classes
An alternative is:
import java.util.*;
public class CarMain {
private Vector<Car> myCars;
...
}
Importing Classes
An alternative is:
import java.util.*;
public class CarMain {
private Vector<Car> myCars;
...
}
Importing Classes
An alternative is:
import java.util.*;
public class CarMain {
private Vector<Car> myCars;
...
}
which directs the compiler to look at all the classes in package java.util.
Importing Classes
This is convenient if you’re using a large number of classes from the same package. For example,
import javax.swing.JButton;
import javax.swing.JFrame;
import javax.swing.JTextArea;
import javax.swing.JTextField;
import java.util.Vector;
import java.util.LinkedList;
Importing Classes
This is convenient if you’re using a large number of classes from the same package. For example,
import javax.swing.JButton;
import javax.swing.JFrame;
import javax.swing.JTextArea;
import javax.swing.JTextField;
import java.util.Vector;
import java.util.LinkedList;
Importing Classes
This is convenient if you’re using a large number of classes from the same package. For example,
import javax.swing.JButton;
import javax.swing.JFrame;
import javax.swing.JTextArea;
import javax.swing.JTextField;
import java.util.Vector;
import java.util.LinkedList;
could simply be written as:
import javax.swing.*;import java.util.*;
Importing Classes
This is convenient if you’re using a large number of classes from the same package. For example,
import javax.swing.JButton;
import javax.swing.JFrame;
import javax.swing.JTextArea;
import javax.swing.JTextField;
import java.util.Vector;
import java.util.LinkedList;
could simply be written as:
import javax.swing.*;import java.util.*;
but many programmers prefer to explicitly list all the classes they use as a form of documentation.
Documentation
One of the ways we view classes is implementations of ADTs.Once they are written, they can be used and re-used.— How many applications use class javax.swing.JButton, or java.util.ArrayList?
In order to be (re)useful — to other programmers (across the world, or maybe just in another team in the same development project), or even to the original programmer (it can be hard going back to code you wrote even a couple of days ago) — the class must be clearly documented.
Documentation
One of the ways we view classes is implementations of ADTs.Once they are written, they can be used and re-used.— How many applications use class javax.swing.JButton, or java.util.ArrayList?
In order to be (re)useful — to other programmers (across the world, or maybe just in another team in the same development project), or even to the original programmer (it can be hard going back to code you wrote even a couple of days ago) — the class must be clearly documented.
Documentation
One of the ways we view classes is implementations of ADTs.Once they are written, they can be used and re-used.— How many applications use class javax.swing.JButton, or java.util.ArrayList?
In order to be (re)useful — to other programmers (across the world, or maybe just in another team in the same development project), or even to the original programmer (it can be hard going back to code you wrote even a couple of days ago) — the class must be clearly documented.
APIs
An API (Application Program Interface) for a package lists all the public classes in that package.
For each public class, there is a list of its (public or protected):
• constants
• fields
• constructors
• methods
Each of these members has some accompanying documentation.
APIs
An API (Application Program Interface) for a package lists all the public classes in that package.
For each public class, there is a list of its (public or protected):
• constants
• fields
• constructors
• methods
Each of these members has some accompanying documentation.
APIs
An API (Application Program Interface) for a package lists all the public classes in that package.
For each public class, there is a list of its (public or protected):
• constants
• fields
• constructors
• methods
Each of these members has some accompanying documentation.
APIs
An API (Application Program Interface) for a package lists all the public classes in that package.
For each public class, there is a list of its (public or protected):
• constants
• fields
• constructors
• methods
Each of these members has some accompanying documentation.
APIs
An API (Application Program Interface) for a package lists all the public classes in that package.
For each public class, there is a list of its (public or protected):
• constants
• fields
• constructors
• methods
Each of these members has some accompanying documentation.
APIs
An API (Application Program Interface) for a package lists all the public classes in that package.
For each public class, there is a list of its (public or protected):
• constants
• fields
• constructors
• methods
Each of these members has some accompanying documentation.
APIs
An API (Application Program Interface) for a package lists all the public classes in that package.
For each public class, there is a list of its (public or protected):
• constants
• fields
• constructors
• methods
Each of these members has some accompanying documentation.
Javadoc
Included in the standard distributions of Java is a tool for generating the HTML pages that make up the API documentation.
The tool is called javadoc, and it works on the Java source files in a package (e.g., the default package).
The Java source files should be marked up with special comments preceding each member of the class, as well as the class itself.(By default, javadoc documents only public and protected classes and members, but this default can be overridden.)
Javadoc
Included in the standard distributions of Java is a tool for generating the HTML pages that make up the API documentation.
The tool is called javadoc, and it works on the Java source files in a package (e.g., the default package).
The Java source files should be marked up with special comments preceding each member of the class, as well as the class itself.(By default, javadoc documents only public and protected classes and members, but this default can be overridden.)
Javadoc
Included in the standard distributions of Java is a tool for generating the HTML pages that make up the API documentation.
The tool is called javadoc, and it works on the Java source files in a package (e.g., the default package).
The Java source files should be marked up with special comments preceding each member of the class, as well as the class itself.(By default, javadoc documents only public and protected classes and members, but this default can be overridden.)
Javadoc
Included in the standard distributions of Java is a tool for generating the HTML pages that make up the API documentation.
The tool is called javadoc, and it works on the Java source files in a package (e.g., the default package).
The Java source files should be marked up with special comments preceding each member of the class, as well as the class itself.(By default, javadoc documents only public and protected classes and members, but this default can be overridden.)
Javadoc and APIs
Javadoc is a utility for generating html documentation for classes and packages.
• write the source code, e.g., MyClass.java
• add a javadoc comment for each class and for each of their members
• then, in the command line:
javadoc MyClass.java
…will generate the html files (index.html, MyClass.html, etc.)
The html files will contain all of the javadoc comments from the source-code file.
Javadoc and APIs
Javadoc is a utility for generating html documentation for classes and packages.
• write the source code, e.g., MyClass.java
• add a javadoc comment for each class and for each of their members
• then, in the command line:
…will generate the html files (index.html, MyClass.html, etc.)
The html files will contain all of the javadoc comments from the source-code file.
javadoc MyClass.java
Javadoc and APIs
Javadoc is a utility for generating html documentation for classes and packages.
• write the source code, e.g., MyClass.java
• add a javadoc comment for each class and for each of their members
• then, in the command line:
…will generate the html files (index.html, MyClass.html, etc.)
The html files will contain all of the javadoc comments from the source-code file.
javadoc MyClass.java
Javadoc and APIs
Javadoc is a utility for generating html documentation for classes and packages.
• write the source code, e.g., MyClass.java
• add a javadoc comment for each class and for each of their members
• then, in the command line:
javadoc MyClass.java
…will generate the html files (index.html, MyClass.html, etc.)
The html files will contain all of the javadoc comments from the source-code file.
Javadoc and APIs
Javadoc is a utility for generating html documentation for classes and packages.
• write the source code, e.g., MyClass.java
• add a javadoc comment for each class and for each of their members
• then, in the command line:
javadoc MyClass.java
…will generate the html files (index.html, MyClass.html, etc.)
The html files will contain all of the javadoc comments from the source-code file.
Javadoc Comments
Javadoc comments are like standard multi-line comments, but begin with a slash followed by two asterisks:
/***An unsorted list of objects.*There are operations to add, find, remove an element*inside the list, as well as check if an element is in*the list.*...*/public class ArrayUnsortedList implements ListInterface {...}
Javadoc Comments
Javadoc comments are like standard multi-line comments, but begin with a slash followed by two asterisks:
/***An unsorted list of objects.*There are operations to add, find, remove an element*inside the list, as well as check if an element is in*the list.*...*/public class ArrayUnsortedList implements ListInterface {...}
Javadoc Comments
Javadoc comments are like standard multi-line comments, but begin with a slash followed by two asterisks:
/***An unsorted list of objects.*There are operations to add, find, remove an element*inside the list, as well as check if an element is in*the list.*...*/public class ArrayUnsortedList implements ListInterface {...}
Javadoc Comments
• The first sentence should be a summary of the thing being documented (class, field, method, etc.).
• This will be used in the corresponding ‘Summary’ section of the API.
• Note: ‘sentence’ means everything up to the first full stop “.” followed by white space (space, new line, tab, etc.)
Javadoc Comments
• The first sentence should be a summary of the thing being documented (class, field, method, etc.).
• This will be used in the corresponding ‘Summary’ section of the API.
• Note: ‘sentence’ means everything up to the first full stop “.” followed by white space (space, new line, tab, etc.)
Javadoc Comments
• The first sentence should be a summary of the thing being documented (class, field, method, etc.).
• This will be used in the corresponding ‘Summary’ section of the API.
• Note: ‘sentence’ means everything up to the first full stop “.” followed by white space (space, new line, tab, etc.)
Javadoc Comments
For example, if the input contains:
/** Increments the capacity of the list by an amount equal to the* original capacity.* Creates a larger array and copies all the list elements to the* new larger array.*/
protected void enlarge() {...
}
Javadoc Comments
For example, if the input contains:
/** Increments the capacity of the list by an amount equal to the* original capacity.* Creates a larger array and copies all the list elements to the* new larger array.*/
protected void enlarge() {...
}
Javadoc Comments
…the output (in the ArrayUnsortedList API) will have, in the ‘Method Summary’ section:
void enlarge()
Increments the capacity of the list by an amount equal to the original capacity.
Javadoc Comments
…the output (in the ArrayUnsortedList API) will have, in the ‘Method Summary’ section:
void enlarge()
Increments the capacity of the list by an amount equal to the original capacity.
and in the ‘Method Detail’ section:
public void enlarge()
Increments the capacity of the list by an amount equal to the original capacity.
Creates a larger array and copies all the list elements to the new larger array.
Javadoc Comments
All comments can (should) be marked-up HTML, and can contain any HTML tag.
/*** A Car has:* <ul>* <li>a brand;</li>* <li>a model;</li>* <li>a colour;</li>* ...* </ul>*/public class Car {
...}
Javadoc Comments
All comments can (should) be marked-up HTML, and can contain any HTML tag.
/*** A Car has:* <ul>* a brand;* a model;* a colour;* ...* */public class Car {
...}
Javadoc Comments
All comments can (should) be marked-up HTML, and can contain any HTML tag.
/*** A Car has:* <ul>* <li>a brand;</li>* <li>a model;</li>* <li>a colour;</li>* ...* </ul>*/public class Car {
...}
Javadoc Tags
In addition, there are certain tags specific to javadoc.The most useful are:
• @param— describe parameters to a method
• @return— describe the return value of a method
• @link— cross-reference another item in the API
Javadoc Tags
In addition, there are certain tags specific to javadoc.The most useful are:
• @param— describe parameters to a method
• @return— describe the return value of a method
• @link— cross-reference another item in the API
Javadoc Tags
In addition, there are certain tags specific to javadoc.The most useful are:
• @param— describe parameters to a method
• @return— describe the return value of a method
• @link— cross-reference another item in the API
Javadoc Tags
In addition, there are certain tags specific to javadoc.The most useful are:
• @param— describe parameters to a method
• @return— describe the return value of a method
• @link— cross-reference another item in the API
Javadoc Tags
In addition, there are certain tags specific to javadoc.The most useful are:
• @param— describe parameters to a method
• @return— describe the return value of a method
• @link— cross-reference another item in the API
Javadoc Tags
For methods, there are @param and @return tags:
/*** Find if a given element exists in the list.* @param element the element to be found* @return <code>true</code> if there is an item of the list that equals the* given element.*/public boolean contains(Object element) {
...}
Javadoc Tags
For methods, there are @param and @return tags:
/*** Find if a given element exists in the list.* @param element the element to be found* @return <code>true</code> if there is an item of the list that equals the* given element.*/public boolean contains(Object element) {
...}
Javadoc Tags
For methods, there are @param and @return tags:
/*** Find if a given element exists in the list.* @param element the element to be found* @return <code>true</code> if there is an item of the list that equals the* given element.*/public boolean contains(Object element) {
...}
There should be one @param tag for each parameter.
@return should be used for every method with a non-void return type.
Javadoc Tags
For methods, there are @param and @return tags:
/*** Find if a given element exists in the list.* @param element the element to be found* @return <code>true</code> if there is an item of the list that equals the* given element.*/public boolean contains(Object element) {
...}
There should be one @param tag for each parameter.
@return should be used for every method with a non-void return type.
Javadoc Tags
This will produce, in the Method Detail section:
public boolean contains(java.lang.Object element)
Find if a given element exists in the list.
Parameters:element — the element to be found
Returns:true if there is an item of the list that equals the given element.
Javadoc Cross-References
Cross-referencing (generating hyper-links in the HTML pages) can be done with the @link tag.
The general format is: {@link Link-Name Text}
This creates a hyper-link where:
• Text is the text displayed in the hyperlink
• Link-Name is the target (in javadoc notation!)
Javadoc Cross-References
Cross-referencing (generating hyper-links in the HTML pages) can be done with the @link tag.
The general format is: {@link Link-Name Text}
This creates a hyper-link where:
• Text is the text displayed in the hyperlink
• Link-Name is the target (in javadoc notation!)
Javadoc Cross-References
Cross-referencing (generating hyper-links in the HTML pages) can be done with the @link tag.
The general format is: {@link Link-Name Text}
This creates a hyper-link where:
• Text is the text displayed in the hyperlink
• Link-Name is the target (in javadoc notation!)
Javadoc Cross-References
Cross-referencing (generating hyper-links in the HTML pages) can be done with the @link tag.
The general format is: {@link Link-Name Text}
This creates a hyper-link where:
• Text is the text displayed in the hyperlink
• Link-Name is the target (in javadoc notation!)
Javadoc Cross-References
Cross-referencing (generating hyper-links in the HTML pages) can be done with the @link tag.
The general format is: {@link Link-Name Text}
This creates a hyper-link where:
• Text is the text displayed in the hyperlink
• Link-Name is the target (in javadoc notation!)
Javadoc Cross-References
The Link-Name is either:
• just the name of a class in the same package
... implementation of the {@link ArrayUnsortedList ArrayUnsortedList} ...
Javadoc Cross-References
The Link-Name is either:
• just the name of a class in the same package
... implementation of the {@link ArrayUnsortedList ArrayUnsortedList} ...
• the name of a member within the class
... invokes the method {@link #find(Object) find} ...
Javadoc Cross-References
The Link-Name is either:
• just the name of a class in the same package
... implementation of the {@link ArrayUnsortedList ArrayUnsortedList} ...
• the name of a member within the class
... invokes the method {@link #find(Object) find} ...
Note: the link-names for methods always include brackets, which must contain the types only of any parameters.
Javadoc Cross-References
The Link-Name is either:
• just the name of a class in the same package
... implementation of the {@link ArrayUnsortedList ArrayUnsortedList} ...
• the name of a member within the class
... invokes the method {@link #find(Object) find} ...
• the name of a member in some other class
... by {@link ArrayUnsortedList#DEFCAP the default capacity}...
Note: the link-names for methods always include brackets, which must contain the types only of any parameters.
Javadoc Cross-References
The generated link points to the relevant part of the API pages.
For example,
... invokes the method {@link #find(Object) find} ...
will produce an html file containing:
… invokes the method find ...
with the hyperlink pointing to the part of ArrayUnsortedList.html where the method find is described.
Javadoc Cross-References
The generated link points to the relevant part of the API pages.
For example,
... invokes the method {@link #find(Object) find} ...
will produce an html file containing:
… invokes the method find ...
with the hyperlink pointing to the part of ArrayUnsortedList.html where the method find is described.
Javadoc Cross-References
The generated link points to the relevant part of the API pages.
For example,
... invokes the method {@link #find(Object) find} ...
will produce an html file containing:
… invokes the method find ...
with the hyperlink pointing to the part of ArrayUnsortedList.html where the method find is described.
Javadoc Cross-References
The generated link points to the relevant part of the API pages.
For example,
... invokes the method {@link #find(Object) find} ...
will produce an html file containing:
… invokes the method find ...
with the hyperlink pointing to the part of ArrayUnsortedList.html where the method find is described.
Important Points
• Javadoc comments come immediately before the thing they describe.
• They can describe: classes, methods, and fields.
• They cannot be used inside methods (well, they can, but they’ll be ignored, so just use standard in-line comments// ...
and/*...*/
).
Important Points
• Javadoc comments come immediately before the thing they describe.
• They can describe: classes, methods, and fields.
• They cannot be used inside methods (well, they can, but they’ll be ignored, so just use standard in-line comments// ...
and/*...*/
).
Important Points
• Javadoc comments come immediately before the thing they describe.
• They can describe: classes, methods, and fields.
• They cannot be used inside methods (well, they can, but they’ll be ignored, so just use standard in-line comments// ...
and/*...*/
).
Good Practice
• one javadoc comment for each class
• one javadoc comment for each member of a class (public, protected, or private)
• always use @param for each parameter
• always use @return for non-void return types
• comments should be useful
Good Practice
• one javadoc comment for each class
• one javadoc comment for each member of a class (public, protected, or private)
• always use @param for each parameter
• always use @return for non-void return types
• comments should be useful
Good Practice
• one javadoc comment for each class
• one javadoc comment for each member of a class (public, protected, or private)
• always use @param for each parameter
• always use @return for non-void return types
• comments should be useful
Good Practice
• one javadoc comment for each class
• one javadoc comment for each member of a class (public, protected, or private)
• always use @param for each parameter
• always use @return for non-void return types
• comments should be useful
Good Practice
• one javadoc comment for each class
• one javadoc comment for each member of a class (public, protected, or private)
• always use @param for each parameter
• always use @return for non-void return types
• comments should be useful
Useful Comments
The point of documenting classes and their members is to help other programmers use your class.(This includes yourself: if there are any private methods in the class, they can only be used inside the class itself; sometimes it can be hard to understand ‘old’ code, even if it’s only a couple of days old.)
Comments should be clear, and say:
• what the thing is for
• how to use the thing
Useful Comments
The point of documenting classes and their members is to help other programmers use your class.(This includes yourself: if there are any private methods in the class, they can only be used inside the class itself; sometimes it can be hard to understand ‘old’ code, even if it’s only a couple of days old.)
Comments should be clear, and say:
• what the thing is for
• how to use the thing
Useful Comments
The point of documenting classes and their members is to help other programmers use your class.(This includes yourself: if there are any private methods in the class, they can only be used inside the class itself; sometimes it can be hard to understand ‘old’ code, even if it’s only a couple of days old.)
Comments should be clear, and say:
• what the thing is for
• how to use the thing
A Bad Comment
This gives no new information; the type of the method is already given in the API page:
/**
*This method takes a String as argument
*and returns a boolean value.
*/
public boolean isIn(String name) { ... }
boolean isIn(String name)
This method takes a String as argument ...
A Bad Comment
/**
*This method takes a String as argument
*and returns a boolean value.
*/
public boolean isIn(String name) { ... }
This gives no new information; the type of the method is already given in the API page:
boolean isIn(String name)
This method takes a String as argument ...
A Bad Comment
This gives no new information; the type of the method is already given in the API page:
/**
*This method takes a String as argument
*and returns a boolean value.
*/
public boolean isIn(String name) { ... }
boolean isIn(String name)
This method takes a String as argument ...
A Bad Comment
Far too detailed…
and the details aren’t relevant!
/**
*This method computes the length of a list
*by looping through the nodes, traversing
*through the nodes and incrementing the len
*variable on each iteration.
*/
public int length() { ... }
A Bad Comment
Far too detailed…
and the details aren’t relevant!
/**
*This method computes the length of a list
*by looping through the nodes, traversing
*through the nodes and incrementing the len
*variable on each iteration.
*/
public int length() { ... }
A Bad Comment
Far too detailed…
and the details aren’t relevant!
/**
*This method computes the length of a list
*by looping through the nodes, traversing
*through the nodes and incrementing the len
*variable on each iteration.
*/
public int length() { ... }
A Bad Comment
/**
*Returns the number of {@link Car Cars}
*in the list.
*/
public int length() { ... }
It should use the @return tag.
A Bad Comment
It should use the @return tag.
/**
*Returns the number of {@link Car Cars}
*in the list.
*/
public int length() { ... }
A Bad Comment
/**
* Adds the given element to the queue, wrapping
* around the underlying array, if needed.
*/
public void enqueue(Object element) {
...
rear = (rear+1)%queue.length;
queue[rear] = element;
...
}
A Bad Comment
Too detailed: the user doesn’t need to know the implementation details; better to say ‘the number of BandCards in the list.
/**
* Adds the given element to the queue, wrapping
* around the underlying array, if needed.
*/
public void enqueue(Object element) {
...
rear = (rear+1)%queue.length;
queue[rear] = element;
...
}
More Information
For more information on javadoc:
• The Java documentation(see the link from the module web-page)
• The examples on the old module web-pages(see the link to “Past Lectures Material” on the module web-page)
Summary
• import
• javadoc
• comments
• Next: Java Collections
top related