Page 805 - Introduction to Programming with Java: A Problem Solving Approach

APPENDIX 6
Javadoc
Appendix 5 describes a programming style that’s optimized for code presentation in an introductory text- book and students writing relatively simple programs. Most of the suggestions there carry over to profes- sional programming practice. But there are some notable exceptions. In professional programming you need to provide interface information about already-compiled classes like the documentation Sun provides for its Java API classes. This appendix shows how to embed interface information in your Java source code so that a special program called javadoc can extract it, convert it into HTML, and display it like Sun displays its description of the Java API.
The javadoc executable comes in the same directory as the javac and java executables, so if you can run javac and java, you can run javadoc also. To run javadoc, at a command prompt, enter this command:
Apago PDF Enhancer
javadoc -d <output-directory> <source-files>
The-d <output-directory>option(“d”means“destination”)causestheoutputtogotoanotherdirectory.
If you omit this -d option, by default the output goes to the current directory, but that’s not a good idea,
because javadoc creates many files that would clutter up the current directory. You can put documenta-
tion for more than one class in the same directory. Use spaces to separate multiple source-file names with
1
presented in Figure A5.1 in Appendix 5. Assuming you are currently in the directory that contains the source code, and assuming that you want javadoc’s output to go to a subdirectory called docs, here’s what the command would look like:
javadoc -d docs Student.java
To see the output, open a Web browser like Windows Explorer, navigate to the docs file, and click on index.html. Figures A6.1 shows the top part of the interface document that javadoc creates—the “Summary” information. This interface document contains an impressive amount of information—but not quite everything we need. For example, it doesn’t include the comment in the last line of the prologue that describes the class in general, it doesn’t include the comment that describes the two-parameter constructor, and it doesn’t include the comments that describe the three methods.
To enable javadoc to extract this other information from source code, we need for all interface in- formation to be located immediately above the heading of whatever it is describing. Also, we need for this
spaces.
Suppose you want to generate interface documentation on the Student class whose source code is
1 To see other options and other argument possibilities, enter javadoc by itself.
771