Recitation 3, week of 17 September:

    (a) Javadoc
    (b) Getting the Java API specs
    (c) An overview of some of the Java API classes
    
Study section 3.3, Javadoc, pp. 65-67.

One problem with keeping documentation (or the specification) of a program separate from
the program is that it is hard to keep the two in synch, especially if they are separated.
Change the program --who is going to find the specification and change it to fit the
changed program? No one.

And yet, the USER of a class does not need the class; he needs only the SPECIFICATION of
the class, so the user WANTS a separate document.

Java solves this problem by allowing the programmer to keep specification and program
together in the .java file and having a program, called javadoc, produce the specification
(as a set of html files) from the .java file. To do this, the specification has to be in a
special form.

Precede the first line, "public class X", by a comment of the form

    /** here is a description of the
        class.
     */

Precede each public (and protected, if you want) variable and method by a comment of the
same form. The comments are assumed to be specifications of the classes and methods. Run
the program

javadoc X.java or javadoc *.java        (to process all .java files)

and javadoc extracts the specially formatted comments and writes them as specifications of
the class and methods in an html file. Program javadoc actually produces a collection of
html files. EVERYONE IN THE CLASS SHOULD TRY THIS OUT TO SEE WHAT IS PRODUCED!

****************************

Note: You can put a few html commands in the comments --use <br> to get a new line,
<b>...</b> to get boldface, etc. Try it out. This enforces the view that the
specification-comments are REALLY there for the purpose of producing the html form of the
specification.

Note: For those of you who have the paperback companion to ProgramLive (by Gries and
Gries), turn to Appendix D, which contains specifications of parts of the Java API
classes. These were produced using a modification of program javadoc, and also using a
version of the API source that had OUR specifications instead of the original ones. Our
version of javadoc produced "latex source" output instead of html files, which we then
processed using latex.

Note: Read Weiss, section 3.3, for more information on the format of javadoc comments.

***************************

IMPORTANT POINT. When using Javadoc and producing the specification, which is separate
from the program, one sees the importance of having a precise specification, which
explains what each parameter is for! Because the body of the method is not available to
look at!

***************************

USING JAVADOC WITH CODEWARRIOR

You can probably use javadoc with other IDEs too; you just have to figure out how.

Codewarrior 6, but not the Codewarrior learning edition, has a javadoc feature. To
find out what to do, 

  (1) Select menu Help item CodeWarrior IDE Help
  (2) Type "javadoc" in the search window and press the SEARCH button
  (3) In the window that comes up, click "Broaden my search"
  (4) In the window that comes up, click the top entry,
      Targeting the Java VM, javadoc
  (5) In the window that comes up, read and follow the instructions.
 
In case you can't get all the CodeWarrior IDE Help because you didn't install enough of
codewarrior, do the following (with a CodeWarrior project open):

  (1) Click the "target" icon in the project window.
  (2) Choose Target -> Target Setting in the panel on the left
  (3) Fix the "Pre-linker" field to be "JavaDoc Pre Linker"
  
  (4) Choose Linker -> javaDoc in the panel on the left
  (5) Make sure "Output as folder hierarchy" is selected
      leave everything else alone
  (6) Click the Save button on the lower right
  (7) Close the " ... Setting" window
  
Now, whenever you have changed your program --including fixing the comments before methods
to be javadoc comments-- choose menu Project item Make. This will cause your program to be
compiled and the javadoc specs to be created. Open folder Docs (in your project directory)
and doubleclick on "tree.html" to open that file in your default browser. Now, browse that
page and look at your extracted specification!!!

*************************

THE SPECS FOR THE JAVA APIS

By the Java APIs (Application Programmer Interfaces) we mean the specs for all the
packages that come with Java --java.lang, java.util, java.io, and so forth. You should
becme familiar with these classes and REGULARLY reference their specifications when
programming. A (partial) specification is included as Appendix D to the paperback
companion to ProgramLive (by Gries and Gries). You can also reference the complete specs
produced by Sun on the web (in html), and you can download the specification to your
computer so that you can reference it when you are not on the web --if you have the space.

Look at this site for general information on documentation for Java 2

    http://java.sun.com/products/jdk/1.2/docs/
    
This is the site for looking at the API specs online, using frames

    http://java.sun.com/products/jdk/1.2/docs/api/index.html
    
This is the site for looking at the API specs online, but without frames:

    http://java.sun.com/products/jdk/1.2/docs/api/overview-summary.html
    
To download the Java API specs, we think ou have to download a much larger file,
unzip it, and delete what you don't want. Take a look at this site, for downloading
for windows or unix:

    http://java.sun.com/products/jdk/1.2/download-docs.html
    
This is the site for downloading the Java Language Specification:

    http://java.sun.com/docs/books/jls/index.html
    
************************

THE PRIMITIVE-TYPE WRAPPER CLASSES:

These are Byte, Short, Integer, Long, Float, Double, Boolean, and Character.
An instance of each contains a single, immutable (unchangeable), value of
the obvious primitive type. In addition, each has various methods: Here they are,
for class Integer; the others are similar:

// An instance wraps a value of type int.
public class Integer

// Constructor: an instance of Integer that wraps integer v
public Integer(int v)

// Constructor: an instance of Integer that wraps the integer represented by s, which
// must contains an integer, with no whitespace
public Integer(String s) throws NumberFormatException

// = the wrapped value of this Integer as a byte
public byte byteValue()

// = the wrapped value of this Integer as a short
public short shortValue()

// = the wrapped value of this Integer as an int
public int intValue()

// = the wrapped value of this Integer as a long
public long longValue()

// = the wrapped value of this Integer as a float
public float floatValue()

// = the wrapped value of this Integer as a double
public double doubleValue()

// = a String representation of the wrapped value of this Integer
public String toString()

// = "obj is not null and is an Integer that wraps the same int as this Integer";
public boolean equals(Object obj)

// The largest value of type int
public static final int MAX_VALUE

// The smallest value of type int
public static final int MIN_VALUE

// = Decimal representation of i
public static String toString(int i)

// = Binary representation of i
public static String toBinaryString(int i)

// = Octal representation of i (see above)
public static String toOctalString(int i)

// = Hexadecimal representation of i
public static String toHexString(int i)

// = a wrapper for the integer whose decimal representation is s,
//   which may not contain whitespace
public static Integer valueOf(String s) throws NumberFormatException

// = the integer whose decimal representation is s,
//   which may not contain whitespace
public static int parseInt(String s) throws NumberFormatException

// = a wrapper for the integer whose representation is nm. nm must contain an
//   integer (in the range of type int) in one of the following three forms:
//   1. A decimal integer with no leading 0's, possibly preceded by a minus sign,
//   2. An octal integer: 0 followed by one or more octal digits 0..7,
//   3. A hexadecimal integer: 0x followed by one or more hexadecimal digits 0..F.
//   nm may not contain whitespace
public static Integer decode(String nm) throws NumberFormatException

************************

Here are methods of class Character

// An instance wraps a char value
public class Character

// Constructor: an instance of Character that wraps c
public Character(char c)</java>

// = the wrapped value of this Character as a char
public char charValue()</java>

// = a String representation of the wrapped value of this Character
public String toString()

// = "obj is not null and is a Character that wraps the same char value as this"
public boolean equals(Object obj)

// The largest value of type char
public static final char MAX_VALUE

// The smallest value of type char
public static final char MIN_VALUE

// = the lower-case equivalent of c (or c itself if c has no lower-case equivalent)
public static char toLowerCase(char c)

// = the upper-case equivalent of c (or c itself if c has no upper-case equivalent)
public static char toUpperCase(char c)

// = "c is a lower-case character"
//   Characters ab...z are lower case, but there are others.
public static boolean isLowerCase(char c)

// = "c is an upper-case character"
//   Characters AB...Z are upper case, but there are others.
public static boolean isUpperCase(char c)

// = "c is a digit" 
//    Characters 0..9 are digits, but there are digits in other languages as well.
public static boolean isDigit(char c)

// = "c is a letter"
//    Characters ab..z and AB..Z are letters, but there are others.
public static boolean isLetter(char c)

// = "c is a letter or a digit". See methods isDigit and isLetter
public static boolean isLetterOrDigit(char c)

// = "c can be the first character of a Java identifier"
public static boolean isJavaIdentifierStart(char c)
 
// = "c can appear in a Java identifier"
public static boolean isJavaIdentifierPart(char c)

// = "c is a space character".
public static boolean isSpaceChar(char c)

// = c is a whitespace character (i.e. space, horizontal tab, vertical tab, line 
//   feed, form feed, carriage return, plus some others).
public static boolean isWhitespace(char c)
 
Class Character has byte constants that are used to denote classes of characters. For
example, constant LETTER_NUMBER is used to represent any character that is either a letter
or a number. These constants are used in several other classes that deal with
input/output. The specification in java.lang.Character.html has no explanation of these
constants other than the names. Any use of these will be explained where they are used. We
list a few of these constants here.

public static final byte UPPERCASE_LETTER
public static final byte LOWERCASE_LETTER
public static final byte ENCLOSING_MARK
public static final byte DECIMAL_DIGIT_NUMBER
public static final byte LETTER_NUMBER
public static final byte SPACE_SEPARATOR
public static final byte LINE_SEPARATOR
public static final byte DASH_PUNCTUATION
public static final byte MATH_SYMBOL
public static final byte CURRENCY_SYMBOL

***************************

// An instance is a string (sequence) of characters
public class String

// Constructor: a String of length 0
public String()

// Constructor: a String containing the chars in array c
public String(char[] c)

// Constructor: a (new) String containing the chars in s
public String(String s)

// Constructor: a String containing the chars in s
public String(StringBuffer s)

// = the length (number of characters) in this String
public int length()

// = the character at index i of this String
public char charAt(int i) throws StringIndexOutOfBoundsException

// = the substring this[i..]. Exception is thrown if !(0 <= i <= this.length())
public String substring(int i) throws StringIndexOutOfBoundsException

// = the substring this[i..j-1]. Exceptionthrown if !(0 <= i <= j < this.length()).
// Note that this.substring(i,i) is the empty String beginning at this[0]
public String substring(int i, int j) throws StringIndexOutOfBoundsException

// = a new String consisting of this String followed by the characters of s.
public String concat(String s)

// = this String
public String toString()

// = "s is a String object and represents the same sequence of chars that this does";
public boolean equals(Object s)

// = "this String and s represent the same sequence of chars, ignoring case"; 
//   --two chars are considered equal if they are the same or if applying 
//   Character.toUpperCase or CharactertoLowerCase to one gives the other.
<public boolean equalsIgnoreCase(String s)

// = 0 if this String and s are equal sequences of chars;
//   = an integer < 0 if this String is lexicographically less than s; 
//   = an integer > 0 if this String is lexicographically greater than s.
public int compareTo(String s)

// = "s is a prefix of this String"
public boolean startsWith(String s)

// = "s is a prefix of this[i..]"
public boolean startsWith(String s, int i)

// = "s is a suffix of this String"
public boolean endsWith(String s)

// = "0 <= i <= i+n <= this.length()  and
//    0 <= j <= j+n <= s.length()     and
//    this[i..i+n-1] = s[j..j+n-1]"
public boolean regionMatches(int i, String s, int j, int n)

// = "0 <= i <= i+n <= this.length()  and
//    0 <= j <= j+n <= s.length()     and
//    this[i..i+n-1] = s[j..j+n-1]". If ig, then the matching is case insensitive.
public boolean regionMatches(boolean ig, int i, String s, int j, int n)

// = the smallest index of an occurrence of c in this String (-1 if none).
public int indexOf(char c)

// = the smallest index >= i of c in this String (-1 if none).
public int indexOf(char c, int i)

// = the smallest index of an occurrence of s in this String (-1 if none).
public int indexOf(String s)

// = the smallest index >= i of an occurrence of s in this String (-1 if none).
public int indexOf(String s, int i)

// = the largest index of an occurrence of c in this String (-1 if none).
public int lastIndexOf(char c)

// = the largest index >= i of an occurrence of c in this String (-1 if none).
public int lastIndexOf(char c, int i)</java>

// = the largest index of an occurrence of s in this String (-1 if none).
public int lastIndexOf(String s)

// = the largest index <= i of an occurrence of s in this String (-1 if none).
public int lastIndexOf(String s, int i)

// = the String that results from replacing all occurrences of co in this by cn.
public String replace(char co, char cn)

// = the String that results by converting each char of this String to lower case
public String toLowerCase()

// = the String that results by converting each char of this String to upper case
public String toUpperCase()

// = this String, but with all whitespace removed from both ends
public String trim()

// = if s = null then null else obj.toString()
public static String valueOf(Object s)

// = a String that contains the chars in d
public static String valueOf(char d[])

// = a String that contains the chars in d[i..i+n-1]
public static String valueOf(char d[], int i, int n)

// = the String representation of b --either "false" or "true"
public static String valueOf(boolean b)

// = the String representation of c
public static String valueOf(char c)

// = the String representation of i --the same as (new Integer(i)).toString();
public static String valueOf(int i)

// = the String representation of l --the same as (new Long(l)).toString();
public static String valueOf(long l)

// = the String representation of f --the same as (new Float(f)).toString();
public static String valueOf(float f)

// = the String representation of d --the same as (new Double(d)).toString();
public static String valueOf(double d)

********************************

Class StringBuffer contains a mutable --changeable-- sequence of characters. The Java
operation String x= "a" + 1; is compiled into the equivalent of:

    String x= new StringBuffer().append("a").append(1).toString();

When a String has to be changed a lot, it may be advantageous to convert it to class
StringBuffer, perform the changes on the StringBuffer, and then convert the result back to
a String.

// An instance contains a MUTABLE sequence of characters
public class StringBuffer

// = a StringBuffer with no chars in it
public StringBuffer()

// = a StringBuffer with the chars of s in it
public StringBuffer(String s)


// = the length (number of characters) in this StringBuffer.
 public int length()

// = the char at index i of this StringBuffer. Must have 0 <= i < this.length()
public char charAt(int i) throws StringIndexOutOfBoundsException

// = the substring this[i..]. Must have 0 <= i < this.length().
public String substring(int i) throws StringIndexOutOfBoundsException

// = the substring this[i..j-1]. Must have 0 <= i <= j < this.length(). 
public String substring(int i, int j) throws StringIndexOutOfBoundsException

// = a String that contains the chars  in this instance
public String toString()

// APPEND the characters of s to this instance. If s=null, use "null" in its place
public void append(String s)

// Change this to this[0..i-1] + s + this[i..]. If s=null, use "null" in its place
public void insert(int i, String s)

Methods insert and append are overloaded, and the argument can be any primitive type or
class, in which case the toString representation of the argument is used.

// Delete substring this[h..k] from this instance
public void delete(int h, int k) 

// Delete char this.charAt(k) from this instance
public void deleteCharAt(int k)

// Replace characters this[h..k] by s; h and k must satisfy h <= k
public void replace(int h, int k, String s)

// Reverse this sequence of chars
public void reverse()

// Change the length of this sequence to h. If h < this.length(), extra null chars 
// ('\u0000') are added. If h < this.length, the suffix of this is deleted
public void setLength(int i)