User Help
User HelpThe user help file is the easiest part of the documentation component. Some developers have used plain text and passed, but do a little more that that. Remember, this part of your project is for the users, so don't get technical. Just tell them what to click and in what order they should do so. Figure 5.1 illustrates user help for the project. Figure 5.1. An example of user help. The example in Listing 5.1 of user help code looks clean, is brief, and meets the requirements. Don't get fancy with too many images, although a screenshot or two is fine. Listing 5.1 A Sample Help File <!--**************************************************************** XHTML tags that contain a trailing slash (e.g., <br />) are not understood by the version of the JTextPane class used in the book because it relies on the class javax.swing.text.html.HTMLEditorKit which provides only HTML 3.2 support. ****************************************************************--> <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN"> <html> <head> <title>Super Bowl Reservation System</title> <style type="text/css"> body { background-color: #ffffff; } span.c1 {color: #CC6600; font-family: Arial} </style> </head> <body topmargin="0" leftmargin="0"> <table border="0" cellpadding="0" cellspacing="0" width="604"> <tr valign="top"> <td width="16"> <p> </p> </td> <td width="100%"> <h1>Super Bowl User Help</h1> <strong>Welcome to the Super Bowl Reservation System (SBRS)</strong> <p>Learn about this application and how to use it.<br> <br> SBRS is ready to help you plan the right trip at the right price, right from your desktop. If you are planning a trip to the Super Bowl, this application will help you.<br> <br> Here is a step-by-step guide to making reservations on SBRS:<br> <br> <span class="c1"><strong>Start planning your trip</strong></span><br> To plan a great trip to the Super Bowl, you must first plan it. Make sure you account for food, hotel, flight, and traffic. You'll appreciate the benefits of advance planning. And if you're traveling with children, talk to them about the trip BEFORE you leave.<br> <br> <span class="c1"><strong>Search a seat</strong></span> <br> You can search for seats right from the main screen. <br><br> <strong>Search Available Seats</strong></p> <ol> <li> In the "Search Seats" area, select a Level in which you wish to sit (or "any" to match all levels).</li> <li>Select the Aisle in which you wish to sit (or "any" to match all aisles).</li> <li> Click the "Search Seats" button. </li> </ol> <p>OR</p> <ol> <li> In the table in the bottom half of the screen, you can click on any Level or Aisle value to update the Level and Aisle values shown in the Search Seats area. </li> <li> Click the "Search Seats" button. </li> </ol> <p>Either set of steps will show all seats that match your criteria.</p> <p><span class="c1"><strong>Reserve a seat</strong></span></p> <ol> <li> If you don't immediately see the seat you want, please follow the above instructions to search for seats that interest you. </li> <li> Click on a seat in the table. You can click anywhere in the row corresponding to that seat. </li> <li> This action will enter the seat number under the "Reserve Seats" section in the upper left. </li> <li> Now type in the number of seats you want to reserve. Note that the maximum number of seats available is displayed in parentheses to the immediate right of "How Many Seats." </li> <li> Click on the "Reserve Seat" button. </li> <li> The number of seats you reserve will be deducted from the "Available" column. </li> </ol> <span class="c1"><strong>We're here if you need us</strong> </span> <br> When you have questions, call us for the information you need.<br> <br> Our customer support representatives are ready to assist you 24 hours a day, 7 days a week. Fill out our support and feedback form and we'll respond within 4 hours, guaranteed. If you need immediate assistance, call us at (800) 555-6666 or (111) 555-0000.<br> <br> <strong>Candidate</strong><br> <em>Alain Trottier</em><br> <em>Sun Certified Java Developer</em></td> </tr> </table> </body> </html> Javadoc Code CommentsJavadoc documentation has been mentioned in previous chapters, but in this chapter, you see the five main uses of javadoc: file, class, method, field, and statement headers. Table 5.1 offers a quick review of the special tags that Javadoc pulls from the source comments and where you are likely to use these tags. Table 5.1. Javadoc Tags
The following list defines the tags shown in Table 5.1:
The following are examples from the SDK source javadoc documentation. The majority of the javadoc comments go into what some call "block headers." The first one goes at the top of the file and describes the file. The rest are placed immediately preceding the declarations for the class, method, and field. File HeaderEach source file should begin with a multiline comment that mentions its purpose, author, and date. The following is an example of a package header javadoc comment: j Class HeaderThe following is an example of a class header javadoc comment from the SDK WeakReference class source: /** * Weak reference objects, which do not prevent their * referents from being made finalizable, finalized, and * then reclaimed. Weak references are most * often used to implement canonicalizing mappings. * * <p> Suppose that the garbage collector determines at a * certain point in time that an object is * <a href="package-summary.html#reachability">weakly * reachable</a>. At that time it will automatically clear * all weak references to that object and all weak * references to any other weakly reachable objects * from which that object is reachable through a chain of * strong and soft references. At the same time, it will * declare all the formerly weakly reachable objects to * be finalizable. At the same time or at some later time, * it will enqueue those newly cleared weak references that * are registered with reference queues. * * @author some author * @version some date * @since 1.2 */ public class WeakReference extends Reference { Method HeaderThe following is an example of a method header javadoc comment from the SDK Pattern class source: /** * Compiles the given regular expression into a pattern * with the given flags. </p> * * @param regex * The expression to be compiled * * @param flags * Match flags, a bit mask that may include * {@link #CASE_INSENSITIVE}, * {@link #MULTILINE}, {@link #DOTALL}, * {@link #UNICODE_CASE}, and {@link #CANON_EQ} * * @throws IllegalArgumentException * If bit values other than those corresponding * to the defined match flags are set in * <tt>flags</tt> * * @throws PatternSyntaxException * If the expression's syntax is invalid */ public static Pattern compile(String regex, int flags){ return new Pattern(regex, flags); } Field HeaderThe following is an example of a field header javadoc comment from the SDK Pattern class source: /** * Enables case-insensitive matching. * * <p> By default, case-insensitive matching assumes * that only characters in the US-ASCII charset are * being matched. Unicode-aware case-insensitive * matching can be enabled by specifying the {@link * #UNICODE_CASE} flag with this flag. * * <p> Case-insensitive matching can also be enabled * via the embedded flag expression <tt>(?i)</tt>. * * <p> Specifying this flag could impose a slight * performance penalty. </p> */ public static final int CASE_INSENSITIVE = 0x02;  |
EAN: N/A
Pages: 187