1 / 20

Literate Programming

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. Literate Programming in Java.

hilaryd
Download Presentation

Literate Programming

An Image/Link below is provided (as is) to download presentation Download Policy: Content on the Website is provided to you AS IS for your information and personal use and may not be sold / licensed / shared on other websites without getting consent from its author. Content is provided to you AS IS for your information and personal use only. Download presentation by click this link. While downloading, if for some reason you are not able to download a presentation, the publisher may have deleted the file from their server. During download, if you can't get a presentation, the file might be deleted by the publisher.

E N D

Presentation Transcript


  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

More Related