| Java Device Test Suite Developer’s Guide |    
|
| C H A P T E R 5 |
|
Writing Online Documentation |
This chapter describes the online documentation that you must include with the test packs you develop.
A test pack has four levels of increasingly detailed online documents. TABLE 5-1 summarizes the document types. The graphical harness displays a document when a tester selects a test pack, package, case, or class in the test tree and clicks the Documentation tab.
|
The testsuite.html file gives an overview of the test pack. It is described in Documenting a Test Pack. |
|
|
The package.html file describes the test classes or subpackages in the same directory. It is described in Documenting a Test Package. |
|
|
Javadoc tool comment blocks in the source code describe each test class. By default, building a test pack generates HTML file from these comments. These comments are described in Chapter 4. |
|
|
Javadoc tool comment blocks in the source code describe each test case. By default, building a test pack generates HTML file from these comments. These comments are described in Chapter 4. |
Users access test pack documentation from the harness Documentation tab.
Provide overview documentation of a test pack by creating a testsuite.html file in the test pack’s top directory (the same directory that contains testsuite.info). The Java Device Test Suite does not define the content of this file. Its form and content are up to you. FIGURE 5-1 shows one example of test pack documentation.
FIGURE 5-1 Sample Test Pack Documentation
You must supply a package.html file in client functional directories. A non-functional directory is one whose only purpose is to create a unique package name. For example, com/ and sun/ in the built-in and sample test packs are non-functional. The harness displays a package.html file when a tester selects a package in the test tree and clicks the Documentation tab. By default, the build system recursively scans your test pack’s directories and finds all package.html files. If you require finer control, see Chapter 26.
Server directories are not required to have package.html files, but you can provide them to comply with Java coding guidelines (see http://java.sun.com/j2se/javadoc/writingdoccomments/index.html). The harness does not display server package.html files.
Use only simple HTML commands in package.html files. Do not use style sheets, URL links, or browser-specific commands.
Include any information in a package.html file that is helpful to testers or administrators who select the package in the graphical user interface and click the Documentation tab. For example, give an overview of the tests in the package to help a tester or administrator decide if exploration of the package's contents is likely to be worthwhile. Try to answer this question: If you were a tester exploring this package, what would you want to know? If you have no information for testers or administrators, put “No documentation for this package” in the file.