Laboratory. of Java and. specifically. On the line the method. does, e.g.: /** Obtains. of the die.

Transcription

1 ECCS 166 Programming 3 Dr. Estell Spring Quarter 2011 Laboratory Assignment 4 Javadoc 25 March The purpose of this laboratory is to familiarize ourselves with the use of the built-in documentation features of Java and specifically of the NetBeans IDE. Javadoc is a tool that generates html-based documentation in the format of the language reference pages at the java.sun.com website. Javadoc utilizes special comments and keyword tags to embed the reference information into the source code; this information is then used to build the Javadoc web pages that allow one to have on-line documentation support for their code. Launch NetBeans and open the Java application project entitled BeanTest. Open up the source view for the DieLabel.java program. We will work on editing the DieLabel class so that it is "properly"" documented. Go to the line just priorr to the method declaration for getdievalue and type the following character sequence, followed by the Enter key: /** Note what NetBeans just did it used its auto-completion feature to insert stub code for Javadoc comments. A Javadoc-typadditional asterisk (or star) following the slash-star that starts off a multi-line comment. comment block is similar to the comment block form used in C++, except that it has an 4. On the line the method corresponding to line 35 in your source code, provide a short (one sentence) description of what does, e.g.: Obtains the current value of the die.

2 5. The next line contains the Tags are keywords that are recognized by Javadoc and are used to define various fields of information; typical tags used in Java programming indicates an item that will not be supported in a future used to describe an argument passed to a method or describes the data returned by a allows the specification of a link to another, hopefully pertinent, identifies author of a class or describes an exception thrown by a allows for versioning information to be specified. At this time, provide information regarding what is being returned by getdievalue by typing that informationn after tag; when you re finished, it should look something like this: 6. Next, enter the Javadoc for the rolldie() method such that it indicates that the purpose of the method is to randomly roll the die, with the new die value shown in the displayed image, and that the returned value is a random integer between 1 and NUMBER_OF SIDES, inclusive.

3 7. Note that HTML tags can be used within the commenting area for Javadoc; this will allow you to modify your description to include bold, italic and/or underlined font, monospaced code inserts, and hyperlinks to documents. To see this in action, enter the following Javadoc comments for the setdievalue method, according to the references given below, after whatever appears in that line: 43: Sets the die to the specified value. 44: new value for the die within the range [1.. <CODE>NUMBER_OF_SIDES</CODE> ] 45: <CODE> >true</code> if passed value was within the legal range of values, <CODE>false</ /CODE> otherwise. 8. At this time, go up to the Run menu and select Generatee Javadoc : If all goes well, a web site should appear; the purpose of Javadoc is to provide a mechanism for easily generating program documentation. Click on the link for the DieLabell class and scroll down to the bottomm of the page to the Method Detail section (shown below) to see what you have so far developed.

4 9. Add Javadoc for the rolldie() method, and for the DieLabel() constructor method so that it has something meaningful to say. 10. Add Javadoc to the four variables of the class. 11. Edit the Javadoc for the DieLabel class so that there is an accurate description of the purpose of the class. Modify tag so that it has your full name. Add tag as well. 12. Make sure that the "BeanTest" project is selected. Go up too the menu bar and select File Save All. Next, go up to the menu bar and select Build Generate Javadoc for "BeanTest". A web browser will be launched and you'll see the home page for the package. Click on the link for DieLabel and look at the documentation. 13. Go into BeanTest.java and, for demonstration purposes only, start entering in something that applies the setdievalue method on an appropriate object. Note that the autocomplete option will have setdievalue listed as one of the selections; when highlighted, the Javadoc that you just wrote is displayed by NetBeans..

5 14. For more information on Javadoc, please visit the following sites: How to Write Doc Comments for the Javadoc Tool: Requirements for Writing Java API Specifications: Show the instructor the web page generated by Javadoc for the DieLabel class showing definitions for all class variables and methods. Have your lab sheet signed by the instructor and turn it in.