📄 18.doc.html
字号:
<html>
<head>
<title>The Java Language Specification Documentation Comments</title>
</head>
<body BGCOLOR=#eeeeff text=#000000 LINK=#0000ff VLINK=#000077 ALINK=#ff0000>
<a href="index.html">Contents</a> | <a href="17.doc.html">Prev</a> | <a href="19.doc.html">Next</a> | <a href="j.index.doc1.html">Index</a>
<hr><br>
<a name="25978"></a>
<p><strong>
CHAPTER 18 </strong></p>
<a name="25979"></a>
<h1>Documentation Comments</h1>
<hr><p>
<a name="25982"></a>
Java programs can include documentation in their source code, in special documentation
comments <a href="3.doc.html#48125">(§3.7)</a>. Such comments can appear before each class or
interface declaration and before each method, constructor, or field declaration.
Hypertext web pages can then be produced automatically from the source code of
the program and these documentation comments.
<p><a name="25983"></a>
This chapter gives an informal description of documentation comments. A complete formal specification would require a detailed description of those parts of the Hypertext Markup Language (HTML) that can be used within the documentation comments, which is beyond the scope of this specification.<p>
<a name="25984"></a>
<h2>18.1 The Text of a Documentation Comment</h2>
<a name="25985"></a>
The text of a documentation comment consists of the characters between the <code>/**</code>
that begins the comment and the <code>*/</code> that ends it. The text is divided into one or
more lines. On each of these lines, leading <code>*</code> characters are ignored; for lines other
than the first, blanks and tabs preceding the initial <code>*</code> characters are also discarded.
<p><a name="25986"></a>
So, for example, in the comment:<p>
<pre><a name="25987"></a>
/**XYZ
<a name="25988"></a>  ** Initialize to pre-trial defaults.
<a name="45499"></a>  123*/
</pre><a name="45500"></a>
the text of the comment has three lines. The first line consists of the text "<code>XYZ</code>";
the second line consists of the text "<code> Initialize to pre-trial defaults.</code>"
and the third line consists of the text "<code>123</code>"
<p><a name="25991"></a>
<h2>18.2 HTML in a Documentation Comment</h2>
<a name="25992"></a>
Text in a documentation comment may use HTML markers for formatting, with
the exception that the specific markers <code><H1></code>, <code><H2></code>, <code><H3></code>, <code><H4></code>, <code><H5></code>, <code><H6></code>, and
<code><HR></code> are reserved for use by the documentation generator and should not be used
in the text. A complete description of HTML is available from the web site
<code>http://www.w3.org</code> and also through the Internet documentation database at
<code>http://www.internic.net</code>, where the document "Hypertext Markup Language
-Version 2.0" by T. Berners-Lee and D. Connolly may be found as RFC1866.
<p><a name="25993"></a>
<h2>18.3 Summary Sentence and General Description</h2>
<a name="25994"></a>
The first sentence of each documentation comment should be a summary sentence,
containing a concise but complete description of the declared entity. This
sentence ends at the first period that is followed by a blank, tab, or line terminator,
or at the first tagline (as defined below). This simple rule means that a first sentence
such as:
<p><pre><a name="26961"></a>This is a simulation of Prof. Knuth's MIX computer.
</pre><a name="26965"></a>
will not work properly, because the period after the abbreviation "<code>Prof</code>" ends the
first sentence, as far as the Java documentation comment processor is concerned.
Take care to avoid such difficulties.
<p><a name="27193"></a>
Sentences following the summary sentence but preceding the first tagged paragraph (if any) form the general description part of the documentation comment.<p>
<a name="25995"></a>
<h2>18.4 Tagged Paragraphs</h2>
<a name="25996"></a>
A line of a documentation comment that begins with the character <code>@</code> followed by
one of a few special keywords starts a <i>tagged paragraph</i>. The tagged paragraph
also includes any following lines up to, but not including, either the first line of the
next tagged paragraph or the end of the documentation comment.
<p><a name="27211"></a>
Tagged paragraphs identify certain information that has a routine structure, such as the intended purpose of each parameter of a method, in a form that the documentation comment processor can easily marshal into standard typographical formats for purposes of presentation and cross-reference.<p>
<a name="25997"></a>
Different kinds of tagged paragraphs are available for class and interface declarations and for method, field, and constructor declarations.<p>
<a name="27008"></a>
<h3>18.4.1 The <code>@see</code> Tag</h3>
<a name="27009"></a>
The following are examples of <code>@see</code> paragraphs, which may be used in any documentation
comment to indicate a cross-reference to a class, interface, method,
constructor, field, or URL:
<p><pre><a name="27010"></a>
@see java.lang.String
<a name="27084"></a>@see String
<a name="27080"></a>@see java.io.InputStream;
<a name="27012"></a>@see String#equals
<a name="27091"></a>@see java.lang.Object#wait(int)
<a name="27095"></a>@see java.io.RandomAccessFile#RandomAccessFile(File, String)
<a name="27087"></a>@see Character#MAX_RADIX
<a name="27014"></a>@see <a href="spec.html">Java Spec</a>
</pre><a name="27020"></a>
The character <code>#</code> separates the name of a class from the name of one of its fields,
methods, or constructors. One of several overloaded methods or constructors may
be selected by including a parenthesized list of argument types after the method or
constructor name.
<p><a name="27126"></a>
A documentation comment may contain more than one <code>@see</code> tag.<p>
<a name="27024"></a>
<h3>18.4.2 The <code>@author</code> Tag</h3>
<a name="27025"></a>
The following are examples of <code>@author</code> taglines, which may be used in documentation
comments for class and interface declarations:
<p><pre><a name="27032"></a>
@author Mary Wollstonecraft
<a name="27253"></a>@author Hildegard von Bingen
<a name="27254"></a>@author Dorothy Parker
</pre><a name="27255"></a>
The information in an <code>@author</code> paragraph has no special internal structure.<p>
<a name="27167"></a>
A documentation comment may contain more than one <code>@author</code> tag. Alternatively, a single <code>@author</code> paragraph may mention several authors:<p>
<pre><a name="27240"></a>
@author Jack Kent, Peggy Parish, Crockett Johnson,
<a name="27241"></a> James Marshall, Marjorie Weinman Sharmat,
<a name="27250"></a> Robert McCloskey, and Madeleine L'Engle
</pre><a name="43966"></a>
However, we recommend specifying one author per <code>@author</code> paragraph, which
allows the documentation processing tool to provide the correct punctuation in all
circumstances.
<p><a name="27066"></a>
<h3>18.4.3 The <code>@version</code> Tag</h3>
<a name="27044"></a>
The following is an example of a <code>@version</code> paragraph, which may be used in documentation
comments for class and interface declarations:
<p><pre><a name="27054"></a>@version 493.0.1beta
</pre><a name="27169"></a>
The information in a <code>@version</code> paragraph has no special internal structure.<p>
<a name="27170"></a>
A documentation comment may contain at most one <code>@version</code> tag.<p>
<a name="27261"></a>
<h3>18.4.4 The <code>@param</code> Tag</h3>
<a name="27262"></a>
The following are examples of <code>@param</code> paragraphs, which may be used in documentation
comments for method and constructor declarations:
<p><pre><a name="27263"></a>
@param file the file to be searched
<a name="27276"></a>@param pattern
<a name="27280"></a> the pattern to be matched during the search
<a name="27281"></a>@param count      the number of lines to print for each match
</pre><a name="27264"></a>
The information in a <code>@param</code> paragraph should consist of the name of the parameter followed by a short description.<p>
<a name="27265"></a>
A documentation comment may contain more than one <code>@param</code> tag. The usual convention is that if any <code>@param</code> paragraphs are present in a documentation comment, then there should be one <code>@param</code> paragraph for each parameter of the method or constructor, and the <code>@param</code> paragraphs should appear in the order in which the parameters are declared.<p>
<a name="27298"></a>
<h3>18.4.5 The <code>@return</code> Tag</h3>
<a name="27299"></a>
The following is an example of a <code>@return</code> paragraph, which may be used in documentation
comments for declarations of methods whose result type is not <code>void</code>:
<p><pre><a name="27300"></a>@return the number of widgets that pass the quality test
</pre><a name="27301"></a>
The information in a <code>@return</code> paragraph has no special internal structure. The usual convention is that it consists of a short description of the returned value.<p>
<a name="27302"></a>
A documentation comment may contain at most one <code>@return</code> tag.<p>
<a name="27325"></a>
<h3>18.4.6 The <code>@exception</code> Tag</h3>
<a name="27326"></a>
The following is an example of an <code>@exception</code> paragraph, which may be used in
documentation comments for method and constructor declarations:
<p><pre><a name="27343"></a>
@exception IndexOutOfBoundsException
<a name="27356"></a> the matrix is too large
<a name="27349"></a>@exception UnflangedWidgetException the widget does not
<a name="27350"></a> have a flange, or its flange has size zero
<a name="27345"></a>@exception java.io.FileNotFoundException the file
<a name="27346"></a> does not exist
</pre><a name="27358"></a>
The information in an <code>@exception</code> paragraph should consist of the name of an exception class (which may be a simple name or a qualified name) followed by a short description of the circumstances that cause the exception to be thrown.<p>
<a name="27329"></a>
A documentation comment may contain more than one <code>@exception</code> tag.<p>
<a name="26035"></a>
<h2>18.5 Example</h2>
<a name="45314"></a>
Here, as an example, is a version of the source code for the class <code>Object</code> of the
package <code>java.lang</code>, including its documentation comments.
<p><pre><a name="44320"></a>
/*
<a name="44321"></a> * @(#)Object.java 1.37 96/06/26
<a name="44322"></a> *
<a name="44323"></a> * Copyright (c) 1994, 1995, 1996 Sun Microsystems, Inc.
<a name="44324"></a> * All Rights Reserved.
<a name="44325"></a> *
<a name="44326"></a> * Permission to use, copy, modify, and distribute this
<a name="44327"></a> * software and its documentation for NON-COMMERCIAL purposes
<a name="44328"></a> * and without fee is hereby granted provided that this
<a name="44329"></a> * copyright notice appears in all copies. Please refer to
<a name="44330"></a> * the file "copyright.html" for further important copyright
<a name="44331"></a> * and licensing information.
<a name="44332"></a> *
<a name="44333"></a> * SUN MAKES NO REPRESENTATIONS OR WARRANTIES ABOUT THE
<a name="44334"></a> * SUITABILITY OF THE SOFTWARE, EITHER EXPRESS OR IMPLIED,
<a name="44335"></a> * INCLUDING BUT NOT LIMITED TO THE IMPLIED WARRANTIES OF
<a name="44336"></a> * MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE, OR
<a name="44337"></a> * NON-INFRINGEMENT. SUN SHALL NOT BE LIABLE FOR ANY DAMAGES
<a name="44338"></a> * SUFFERED BY LICENSEE AS A RESULT OF USING, MODIFYING OR
<a name="44339"></a> * DISTRIBUTING THIS SOFTWARE OR ITS DERIVATIVES.
<a name="44340"></a> */
<br><br><a name="44342"></a>package java.lang;
<br><a name="44344"></a>
/**
<a name="44345"></a> * The root of the Class hierarchy. Every Class in the
<a name="44346"></a> * system has Object as its ultimate parent. Every variable
<a name="44347"></a> * and method defined here is available in every Object.
<a name="44348"></a> * @see Class
<a name="44349"></a> * @version 1.37, 26 Jun 1996
<a name="44350"></a> */
<br><a name="44351"></a>
public class Object {
<a name="44352"></a> /**
<a name="44353"></a> * Returns the Class of this Object. Java has a runtime
<a name="44354"></a> * representation for classes--a descriptor of type Class
<a name="44355"></a> * --which the method getClass() returns for any Object.
<a name="44356"></a> */
<a name="44357"></a> public final native Class getClass();
<br><a name="44359"></a>
/**
<a name="44360"></a> * Returns a hashcode for this Object.
<a name="44361"></a> * Each Object in the Java system has a hashcode.
<a name="44362"></a> * The hashcode is a number that is usually different
<a name="44363"></a> * for different Objects. It is used when storing Objects
<a name="44364"></a> * in hashtables.
<a name="44365"></a> * Note: hashcodes can be negative as well as positive.
<a name="44366"></a> * @see java.util.Hashtable
<a name="44367"></a> */
<a name="44368"></a> public native int hashCode();
<br><a name="44370"></a>
/**
<a name="44371"></a> * Compares two Objects for equality.
<a name="44372"></a> * Returns a boolean that indicates whether this Object
<a name="44373"></a> * is equivalent to the specified Object. This method is
<a name="44374"></a> * used when an Object is stored in a hashtable.
<a name="44375"></a> * @param obj the Object to compare with
<a name="44376"></a> * @return true if these Objects are equal;
<a name="44377"></a> * false otherwise.
<a name="44378"></a> * @see java.util.Hashtable
<a name="44379"></a> */
<a name="44380"></a> public boolean equals(Object obj) {
<a name="44381"></a> return (this == obj);
<a name="44382"></a> }
<br><a name="44384"></a>
/**
<a name="44385"></a> * Creates a clone of the object. A new instance is
<a name="44386"></a> * allocated and a bitwise clone of the current object
<a name="44387"></a> * is placed in the new object.
<a name="44388"></a> * @return a clone of this Object.
<a name="44389"></a> * @exception OutOfMemoryError If there is not enough
<a name="44390"></a> * memory.
<a name="44391"></a> * @exception CloneNotSupportedException Object
<a name="44392"></a> * explicitly does not want to be
<a name="44393"></a> * cloned, or it does not support
<a name="44394"></a> * the Cloneable interface.
<a name="44395"></a> */
<a name="44396"></a> protected native Object clone()
<a name="44397"></a> throws CloneNotSupportedException;
<br></pre><a name="45327"></a>
<p>
⌨️ 快捷键说明
复制代码
Ctrl + C
搜索代码
Ctrl + F
全屏模式
F11
切换主题
Ctrl + Shift + D
显示快捷键
?
增大字号
Ctrl + =
减小字号
Ctrl + -