Java™ Application Development on Linux - Dator

128Chapter 5The Sun Microsystems Java Software <strong>Development</strong> Kit5.5.3 Javadoc CommentsThere’s more to Javadoc than just documenting the types and names of classes,methods, and arguments. A developer can annotate or supplement the documentationby placing specially formatted comments in his or her code.A Javadoc comment begins with the C-style open comment plus at leastone more asterisk. It ends with a C-style close comment. In other words:/* This is a C-style comment, but itis _not_ a Javadoc comment. *//** This is a C-style comment, but itis also a Javadoc comment. */This isn’t a part of the Java programming language. It is merely a lexical hackto allow the javadoc program to recognize a comment it should pick up andprocess. Javadoc is fairly intelligent about where to place the text extracted froma Javadoc comment. For example, a Javadoc comment placed just before thestart of a class will appear in the class summary on the package page and at thetop of the class detail page. A Javadoc comment placed just before a methodwill appear in the method’s box on the class detail page, and so on.We encourage you to discover for yourself the relationship betweenJavadoc comments and the output of the standard doclet. Use it. Experiment.Or, you can go and read the official Sun Microsystems documentation onJavadoc. 5 That’s your choice.Since comment text is extracted and placed into certain positions in anHTML document, you may use HTML tags in your comments to affect howthey are rendered. Be aware that when you do so, you may get unexpectedresults if you use any custom doclets.There’s more to it than that, however. There are a number of macros thatyou can place in Javadoc comments to mark data of particular significance. Forexample, @author should appear just before the name of the author of aparticular piece of code.These at-tags must appear after all descriptive text in a Javadoc comment. 6A tag must be at the beginning of a line within the comment (ignoring any5. http://java.sun.com/j2se/1.4.2/docs/tooldocs/solaris/javadoc.html6. The exception is embedded tags, which we will discuss in a moment.