1. 1 Lecture 3 Literate Programming Overview  Introduction to javadoc.  Documentation comments.  Documenting java source code.  Generating HTML documentation using javadoc.  Customizing javadoc output: doclets.  Preview: Further OO concepts.

2. 2 Lecture 3 Literate Programming in Java  Literate programming is the combination of documentation and source together in a fashion suited for reading by human beings  It is an easy way of creating reports and documentation at the same time as the program itself, and usually produces nice-looking code as well.  Java supports three kinds of comments:  /* text */ A traditional comment:  // text A single-line comment:  /** documentation */ A documentation comment:  The text enclosed by the ASCII characters /** and */ can be processed by a separate tool to prepare automatically generated documentation of the following class, interface, constructor, or member (method or field) declaration.  Before discussing how documentations are produced let us first describe the java tool used for the task.

3. 3 Lecture 3 Program Comments and javadoc  javadoc is the java tool used to create nice documentation from java programs.  Before javadoc can generate HTML files, you must insert documentation comments in your source program.  Like other commands, documentation comments are not translated into bytecode.  Because javadoc generates HTML, documentation comments can contain HTML tags.  Like HTML tags, javadoc tags (which begin with the @ symbol) can be inserted into documentation comments.  Documentation comments are placed on the line before a class definition, an interface definition, a constructor, a method, and a field.

4. 4 Lecture 3 Some javadoc Tags TagMeaning @authorIdentifies the author of the class @deprecatedSpecifies that a class member is deprecated @exceptionIdentifies an exception thrown by a method @paramDocuments a method's parameter @returnDocuments a method's return value @seeSpecifies a link to another topic @sinceStates the release when a specific change was introduced @throwsSame as @throws @versionSpecifies the version of a class

5. 5 Lecture 3 @see Tag: Some Details The @see Tag: In the previous slide, we have seen various uses of the @see tag. This tag may be used in any documentation comment to indicate a cross-reference to a class, interface, method, constructor, field, or URL such as: @see java.lang.String @see java.io.InputStream; @see String#equals @see java.lang.Object#wait(int) @see java.io.RandomAccessFile#RandomAccessFile(File, String) @see Character#MAX_RADIX @see Java Spec The character # separates the name of a class from the name of one of its fields, methods, or constructors. One of several overloaded methods or constructors may be selected by including a parenthesized list of argument types after the method or constructor name. A documentation comment may contain more than one @see tag.

6. 6 Lecture 3 @author Tag: Some Details The @author Tag: The following are examples of @author taglines, which may be used in documentation comments for class and interface declarations: @author Mary Wollstonecraft @author Hildegard von Bingen @author Dorothy Parker The information in an @author paragraph has no special internal structure. A documentation comment may contain more than one @author tag. Alternatively, a single @author paragraph may mention several authors: @author Jack Kent, Peggy Parish, Crockett Johnson, James Marshall, Marjorie Weinman Sharmat, Robert McCloskey, and Madeleine L'Engle However, Gosling et al. recommend specifying one author per @author paragraph, which allows the documentation processing tool to provide the correct punctuation in all circumstances.

7. 7 Lecture 3 @version Tag: Some Details The @version Tag: The following is an example of a @version paragraph, which may be used in documentation comments for class and interface declarations: @version 493.0.1 beta The information in a @version paragraph has no special internal structure. A documentation comment may contain at most one @version tag. The @param Tag: The following are examples of @param paragraphs, which may be used in documentation comments for method and constructor declarations: @param file - The file to be searched. @param pattern - The pattern to be matched during the search. @param count - The number of lines to print for each match. The information in a @param paragraph should consist of the name of the parameter followed by a short description. A documentation comment may contain more than one @param tag.

8. 8 Lecture 3 @param and @return Tags: Some Details The usual convention is that if any @param paragraphs are present in a documentation comment, then there should be one @param paragraph for each parameter of the method or constructor, and the @param paragraphs should appear in the order in which the parameters are declared. The @return Tag: The following is an example of a @return paragraph, which may be used in documentation comments for declarations of methods whose result type is not void: @return the number of widgets that pass the quality test The information in a @return paragraph has no special internal structure. The usual convention is that it consists of a short description of the returned value. A documentation comment may contain at most one @return tag.

9. 9 Lecture 3 @exception Tag: Some Details The @exception Tag: The following is an example of an @exception paragraph, which may be used in documentation comments for method and constructor declarations: @exception IndexOutOfBoundsException the matrix is too large @exception java.io.FileNotFoundException the file does not exist The information in an @exception paragraph should consist of the name of an exception class (which may be a simple name or a qualified name) followed by a short description of the circumstances that cause the exception to be thrown. A documentation comment may contain more than one @exception tag.

10. 10 Lecture 3 Using Javadoc Program: More Examples /** * @(#)Object.java 1.37 96/06/26 */ package java.lang; /** * The root of the Class hierarchy. * @seeClass * @version1.37, 26 Jun 1996 */ public class Object { public final native Class getClass(); /** * Note: hashcodes can be negative as well as positive. * @seejava.util.Hashtable */

11. 11 Lecture 3 Using Javadoc Program: More Examples (Cont’d) public native int hashCode(); /** * Compares two Objects for equality. * @param obj the Object to compare with * @return true if these Objects are equal; * false otherwise. * @seejava.util.Hashtable */ public boolean equals(Object obj) { return (this == obj); } /** * Creates a clone of the object. * @returna clone of this Object. * @exceptionOutOfMemoryError If there is not enough memory. * @exceptionCloneNotSupportedException Object */

12. 12 Lecture 3 Using Javadoc Program: More Examples (Cont’d) protected native Object clone() throws CloneNotSupportedException; /** * Notifies a single waiting thread on a change in * condition of another thread. The thread effecting * the change notifies the waiting thread using notify(). * Threads that want to wait for a condition to change * before proceeding can call wait(). * The method notify() can be called only by the * thread that is the owner of the current object's * monitor lock. * @seeObject#wait * @seeObject#notifyAll */

13. 13 Lecture 3 Documentation Comments: Example 2 import java.io.*; /** * This class demonstrates documentation comments. * @author ICS201 Instructor * @version 1.2 */ public class SquareNum { /** * This method returns the square of num. * This is a multiline description. You can use * as many lines as you like. * @param num The value to be squared. * @return num squared. */ public double square (double num) { return num*num; }

14. 14 Lecture 3 Documentation Comments: Example 2 (cont.) /** This method inputs a number from the user. * @return The value input as a double. * @see IOException */ public double getNumber() throws IOException { // create a BufferedReader using System.in InputStreamReader isr = new InputStreamReader(System.in); BufferedReader inData = new BufferedReader(isr); String str; double d; str = inData.readLine(); d = Double.parseDouble(str); return d; }

15. 15 Lecture 3 Documentation Comments: Example 2 (cont.) /** * This method demonstrate square * @param args Unused. * @return Nothing. * @exception IOException on input error. * @see IOException */ public static void main(String [] args) throws IOException { SquareNum ob = new SquareNum(); double val; System.out.println("Enter value to be squared:" ); val = ob.getNumber(); val = ob.square(val); System.out.println("Squared value is :"+ val); }

16. 16 Lecture 3 Generating HTML with javadoc : Some command-line options usage: javadoc [options] [packagenames] [sourcefiles] [classnames] [@files] -overview Read overview documentation from HTML file -public Show only public classes and members -protected Show protected/public classes and members (default) -package Show package/protected/public classes and members -private Show all classes and members -help Display command line options -doclet Generate output via alternate doclet -sourcepath Specify where to find source files Provided by Standard doclet: -d Destination directory for output files -version Include @version paragraphs -author Include @author paragraphs -link Create links to javadoc output at

17. 17 Lecture 3 Adding Documentations: Points to Note  javadoc will run on.java source files that are pure stub files with no method bodies.  Placing an import statement between the class documentation and the class declaration is a logic error. This causes the class comment to ignored by javadoc.  Each tag should start on a new line. The tag comments can extend into multiple lines if necessary, but there should be no blank lines in between tags.  Defining several fields in one comma-separated statement with a single comment above that statement, will result in javadoc using that comment for all the fields.  To produce proper javadoc documentation, you must declare every instance variable on a separate line.

18. 18 Lecture 3 Customizing javadoc ’s Output: Doclets  A doclet is a program written with the doclet API that specifies the content and format of the output to be generated by the javadoc tool.  You can write a doclet to generate any kind of text-file output, such as HTML, SGML, XML, RTF, and MIF.  If you do not supply a custom doclet, javadoc uses the default doclet provided by java to generate HTML.  Alternatively, you can subclass appropriate classes in the standard doclet and then add or override methods as necessary to produce the output you want.  A doclet is a program of the form (compiled using javac and passed to javadoc using the –doclet option): import com.sun.javadoc.*; public class MyDoclet{ public static boolean start(RootDoc rd){ … } }

19. 19 Lecture 3 Writing Doclets: An Example import com.sun.javadoc.*; public class ListClass { public static boolean start(RootDoc root) { []ClassDoc [] classes = root.classes(); for (int i = 0; i<classes.length; ++i) System.out.println(classes[i]); return true; }  We must imports the com.sun.javadoc package in order to use the doclet APIs.  The start() method takes a RootDoc parameter that carries information about any options specified on the command line when javadoc is run, and also about the classes and packages upon which javadoc is operating.  RootDoc defines a classes() method that returns a ClassDoc array whose elements represent the classes that javadoc parses.

20. 20 Lecture 3 Writing Doclets: An Example  The doclet API classfiles are in the file lib/tools.jar in the Java 2 SDK, and you therefore need to include tools.jar on the compiler's classpath, as in this example: C:\>javac -classpath C:\jdk1.3\lib\tools.jar ListClass.java  We now run javadoc on MyClass.java using the ListClass doclet as: C:\>javadoc -doclet ListClass -classpath C:\jdk1.3\lib\tools.jar MyClass.java  Note that this command also requires tools.jar to be on the class path.  For further details on this check the javadoc documentation in your JavaCD.  Exercise: Explore the javadoc documentation and try to create your own custom tags.