Literate Programming

1. 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. Lecture 3

2. 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. Lecture 3

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. Lecture 3

4. Some javadoc Tags Lecture 3

5. @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 <a href="spec.html">Java Spec</a> • 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. Lecture 3

6. @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. Lecture 3

7. @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. Lecture 3

8. @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. Lecture 3

9. @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. Lecture 3

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

11. 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. * @see java.util.Hashtable */ public boolean equals(Object obj) { return (this == obj); } /** * Creates a clone of the object. * @return a clone of this Object. * @exception OutOfMemoryError If there is not enough memory. * @exception CloneNotSupportedException Object */ Lecture 3

12. 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(). <p> * <em>The method notify() can be called only by the * thread that is the owner of the current object's * monitor lock.</em> * @see Object#wait * @see Object#notifyAll */ Lecture 3

13. 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; } Lecture 3

14. 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; } Lecture 3

15. 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); } } Lecture 3

16. Generating HTML with javadoc: Some command-line options usage: javadoc [options] [packagenames] [sourcefiles] [classnames] [@files] -overview <file> 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 <class> Generate output via alternate doclet -sourcepath <pathlist> Specify where to find source files Provided by Standard doclet: -d <directory> Destination directory for output files -version Include @version paragraphs -author Include @author paragraphs -link <url> Create links to javadoc output at <url> Lecture 3

17. 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. Lecture 3

18. 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){ … }} Lecture 3

19. 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. Lecture 3

20. 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. Lecture 3