[ Pobierz całość w formacie PDF ]
.86 Thinking in Java www.BruceEckel.com The output for the above code is an HTML file that has the same standard format as all therest of the Java documentation, so users will be comfortable with the format and can easilynavigate your classes.It s worth entering the above code, sending it through javadoc andviewing the resulting HTML file to see the results.Embedded HTMLJavadoc passes HTML commands through to the generated HTML document.This allowsyou full use of HTML; however, the primary motive is to let you format code, such as:/**** System.out.println(new Date());**/You can also use HTML just as you would in any other Web document to format the regulartext in your descriptions:/*** You can even insert a list:** Item one* Item two* Item three**/Note that within the documentation comment, asterisks at the beginning of a line arethrown away by javadoc, along with leading spaces.Javadoc reformats everything so that itconforms to the standard documentation appearance.Don t use headings such as oras embedded HTML because javadoc inserts its own headings and yours will interferewith them.All types of comment documentation  class, variable, and method  can support embeddedHTML.@see: referring to other classesAll three types of comment documentation can contain @see tags, which allow you to referto the documentation in other classes.Javadoc will generate HTML with the @see tagshyperlinked to the other documentation.The forms are:@see classname@see fully-qualified-classname@see fully-qualified-classname#method-nameEach one adds a hyperlinked  See Also entry to the generated documentation.Javadoc willnot check the hyperlinks you give it to make sure they are valid.Chapter 2: Everything is an Object 87 Class documentation tagsAlong with embedded HTML and @see references, class documentation can include tags forversion information and the author s name.Class documentation can also be used forinterfaces (described later in the book).@versionThis is of the form:@version version-informationin which version-information is any significant information you see fit to include.Whenthe -version flag is placed on the javadoc command line, the version information will becalled out specially in the generated HTML documentation.@authorThis is of the form:@author author-informationin which author-information is, presumably, your name, but it could also include youremail address or any other appropriate information.When the -author flag is placed on thejavadoc command line, the author information will be called out specially in the generatedHTML documentation.You can have multiple author tags for a list of authors, but they must be placedconsecutively.All the author information will be lumped together into a single paragraph inthe generated HTML.Variable documentation tagsVariable documentation can include only embedded HTML and @see references.Method documentation tagsAs well as embedded documentation and @see references, methods allow documentationtags for parameters, return values, and exceptions.@paramThis is of the form:@paramparameter-name descriptionin which parameter-name is the identifier in the parameter list, and description is textthat can continue on subsequent lines.The description is considered finished when a newdocumentation tag is encountered.You can have any number of these, presumably one foreach parameter.@returnThis is of the form:88 Thinking in Java www.BruceEckel.com @returndescriptionin which description gives you the meaning of the return value.It can continue onsubsequent lines.@exceptionExceptions will be described in Chapter 9, but briefly they are objects that can be  thrownout of a method if that method fails.Although only one exception object can emerge whenyou call a method, a particular method might produce any number of different types ofexceptions, all of which need descriptions.So the form for the exception tag is:@exception fully-qualified-class-name descriptionin which fully-qualified-class-name gives an unambiguous name of an exception classthat s defined somewhere, and description (which can continue on subsequent lines) tellsyou why this particular type of exception can emerge from the method call.@deprecatedThis is new in Java 1.1.It is used to tag features that were superseded by an improvedfeature.The deprecated tag is a suggestion that you no longer use this particular feature,since sometime in the future it is likely to be removed.Methods that are marked@deprecated cause the compiler to issue warnings if it is used.Documentation exampleHere is the first Java program again, this time with documentation comments added://: Property.javaimport java.util.*;/** The first Thinking in Java example program.* Lists system information on current machine.* @author Bruce Eckel* @author http://www.BruceEckel.com* @version 1.0*/public class Property {/** Sole entry point to class & application* @param args array of string arguments* @return No return value* @exception exceptions No exceptions thrown*/public static void main(String[] args) {System.out.println(new Date());Properties p = System.getProperties();p.list(System.out);System.out.println("--- Memory Usage:");Runtime rt = Runtime.getRuntime();System.out.println("Total Memory = "+ rt.totalMemory()+ " Free Memory = "+ rt.freeMemory());Chapter 2: Everything is an Object 89 }} ///:~The first line://: Property.javauses my own technique of putting a  : as a special marker for the comment line containingthe source file name [ Pobierz całość w formacie PDF ]

  • zanotowane.pl
  • doc.pisz.pl
  • pdf.pisz.pl
  • funlifepok.htw.pl

    •