Movatterモバイル変換

[0]ホーム
URL:

Java SE 24 & JDK 24

JavaDoc Documentation Comment Specification for theStandard Doclet (JDK 24)

This document specifies the form of documentation comments recognizedby thestandarddoclet for thejavadoc tool in JDK 24, usedto generate HTML documentation for an API.

In the context of thejavadoc tool, the interpretationof the content of a documentation comment is up to doclet that is usedto process the comment. Other doclets may accept the same syntax as thestandard doclet, or they may support an alternate syntax. However, dueto support in many tools, the syntax supported by the standard doclethas become ade facto standard.

Documentation Comments

Documentation comments are stylized comments appearing in sourcecode, near to the declarations that they serve to document.

Documentation comments are recognized only when placed immediatelybefore the declaration of a module, package, class, interface,constructor, method, annotation interface element, enum member, orfield. In other words, a documentation comment should appear before anyannotation, modifier, keyword, identifier, or other Java construct thatis part of the declaration.

There are two kinds of documentation comments:traditional documentationcomments, andMarkdowndocumentation comments.

Either kind, or both kinds, may be used in any one source file.

Only one documentation comment per declaration statement isrecognized. If there are multiple documentation comments before adeclaration, the one closest to the beginning of the declaration isused.

Documentation may also be provided in certain files:

HTML files are identified by a filename ending in.html.The content of the<main> element of an HTML file, orthe<body> element if there is no<main> element is processed as if it were the contentof a traditional documentation comment.

Markdown files are identified by a filename ending in.md. The content of a Markdown file is processed as if itwere the content of a Markdown documentation comment.

Traditional DocumentationComments

Traditional documentation comments aretraditionalcomments that begin with/**. If any line in such acommentbegins with asterisks afterany leading whitespace, the leading whitespace and asterisks areremoved. Any whitespace appearing after the asterisks is notremoved.

A traditional documentation comment may containHTML content,inlinetags, andblock tags. You can also useescape sequences to represent charactersthat would otherwise be inconvenient or difficult to represent.

Markdown DocumentationComments

Documentation comments containing Markdown are composed of a seriesof consecutive lines, each beginning with optional whitespace followedby///.

A Markdown documentation comment may containMarkdown content (including HTML wherenecessary),inline tags, andblock tags.

General Syntax

The overall form of a documentation comment is an initialmain description, followed by a series ofblock tags, which provide additionalinformation about the declaration to which the comment applies.Descriptive text may includeinline tags,HTML content, andMarkdown content, as described below.

It is possible to have a comment with only block tags and no maindescription.

For historical reasons, the documentation comment for a package mayinstead be provided in a file calledpackage.html in a sourcedirectory for the package. In this case, the documentation comment isthe content of the<body> tag, and all references toJava types (for example, insee tags) must be fullyqualified. The standard doclet also allows additional documentation tobe provided in files such asoverview.html. The rules for suchcontent are the same as forpackage.html.

Main Description

The main description in a documentation comment is the content fromthe beginning of the comment, up to the first block tag, if there areany, or to the end of the comment, if there are none. Leading andtrailing whitespace is ignored. If there is no such content, the maindescription is said to be missing.

The main description cannot continue after any block tags.

Examples of a missing main description.

The first sentence of the main description should be a summarysentence that contains a concise but complete description of thedeclared entity.

Block Tags

Block tags are of the form@identifiercontent and give additional details to be incorporated into thegenerated documentation. Each block tag must appear at the beginning ofa line, ignoring leading asterisks, whitespace characters, and theinitial comment delimiter (/**). This means you can use the@ character elsewhere in the text, and it will not beinterpreted as the start of a tag. If you want to start a line with the@ character and not have it be interpreted, then use theHTML entity&#064;. The content of a block tag is anytext following the tag up to, but not including, either the next blocktag, or the end of the documentation comment. The content can spanmultiple lines.

There can be any number of block tags; some types of tags can berepeated while others cannot.

Inline Tags

Inline tags are of the form{@identifiercontent} and provide details within the context ofthe enclosing description. They may generally appear whereverdescriptive text and HTML is permitted, although some inline tags mayonly be used at the beginning of the main description.

Some inline tags may contain free-form text. When such textexplicitly contains braces, the braces must be "balanced", implying anequal number of appropriately nested left brace and right bracecharacters, so that the closing brace of the inline tag can bedetermined. No other lexical analysis of the text is performed; inparticular, there is no special consideration of characters like',",\, and@.

Lines beginning with@ that are enclosed within aninline tag are not considered as beginning a block tag.

When the text content is HTML, it may be possible to use entities&lbrace; and&rbrace; to representunbalanced braces.

HTML Content

HTML content is not formally checked, although some tools may providesome amount of checking to help catch common errors.

In order to be able to generate documentation that conforms to theappropriate standards, the following considerations should be taken intoaccount when using HTML constructs in a documentation comment:

Markdown Content

Because horizontal whitespace at the beginning and end of each lineof Markdown code may be significant, the content of such a comment isdetermined as follows:

Note: The policy to remove leading incidental whitespace issimilar to that forString.stripIndent,except that there is no need for any special treatment for a trailingblank line.

There are no restrictions on the characters that may appear after the/// on each line of the comment. In particular, the commentmay contain code samples which may contain comments of their own:

/// Here is an example:////// ```/// /** Hello World! *//// public class HelloWorld {///     public static void main(String... args) {///         System.out.println("Hello World!"); // the traditional example///     }/// }/// ```

As well as serving to visually distinguish the new kind ofdocumentation comment, the use of end-of-line (//) commentseliminates the restrictions on the content of the comment that areinherent with the use of traditional (/* ... */) comments.In particular, it is not possible to use the character sequence*/ within a traditional comment, (JLS3.7) although it may be desirable to do so when writing example codecontaining traditional comments, strings containing "glob" expressions,and strings containing regular expressions.

Note: For a blank line to be included in the comment, itmust begin with any optional whitespace followed by///. Acompletely blank line will cause any preceding and following comment tobe treated as separate comments, in which case, all but the last commentwill be discarded, and only the last comment will be considered as adocumentation comment for any declaration that may follow.

For example:

/// This is an example ...////// ... of a 3-line comment containing a blank line.

The blank line in the following example will terminate the firstcomment, so that the comment that comes after the blank line will betreated as a separate comment.

/// This comment will be treated as a "dangling comment" and will be ignored./// This is the comment for the following declaration.public void m() { }

The same is true for any other comment not beginning with/// that may appear between two///comments.

Syntax

The overall syntax of a Markdown documentation comment is that of theCommonMark variant ofMarkdown. Enhancements to links allow convenient linking to otherprogram elements. SimpleGFM pipetables are supported, as are all JavaDoc tags.

Headings

BothATXheadings andsetextheadings are supported. Unlike HTML headings, Markdown headingsshould start at level 1 and increase from there, whatever the context ofthe documentation comment. (They will be translated to the correctheading level in the generated documentation.)

Links

The general form of areferencelink is[text][label] wheretext is thetext to be displayed, andlabel is a label for thedestination of the link, and which is subsequently defined by a line ofthe form[label]: uri.Collapsedandshortcutforms can also be used when thelabel is the same as thetext.

In a documentation comment, if the label for a reference link is tobe defined explicitly, it must be defined in the same documentationcomment. But, if it is not defined and if it syntactically matches thatof areference to a program element, then itis implicitly defined as a reference to that program element. It is anerror if the label looks like a reference to a program element but thereis no such element.

The following all represent links tojava.lang.Object#hashCode(), albeit with different text tobe displayed:

You can link to any kind of program element, as shown in thefollowing examples:

/// * a module [java.base/]/// * a package [java.util]/// * a class [String]/// * a field [String#CASE_INSENSITIVE_ORDER]/// * a method [String#chars()]

Inlinelinks are also supported in documentation comments, but the helpfulrecognition of program elements as labels means that reference links aregenerally more useful than inline links.

According to the standard rules for reference links, you must escapeany use of square brackets within a reference. This might occur when youare creating a reference to a method with an array parameter. Thefollowing shows a link toString.copyValueOf(char[])

The normal rendering for a reference link is to use the default plainfont. If you wish to use a monospace font, you must enclose the textwithin a code span, using backticks. For references to program elements,monospace font will be used automatically if the text is the same as thereference (such as when using the collapsed or shortcut forms), and thedefault plain font otherwise. The following shows how these formscorrespond to the existinglink andlinkplain tags.

Note: You cannot use a reference link in the first sentenceof any documentation comment that refers to a user-defined linkreference definition elsewhere in the documentation comment; you can usean inline link in this situation instead.

Tables

Simple tables are supported, using the syntax defined inGitHub Flavored Markdown. Forexample, a simple table might be written as follows:

/// | Latin | Greek |/// |-------|-------|/// | a     | alpha |/// | b     | beta  |/// | c     | gamma |

Note: Captions and other features that may be required foraccessibility are not supported. In such situations, the use of HTMLtables is still recommended.

Inline Tags and Block Tags

Bothinline tags andblock tags may be used in Markdown documentationcomments, although neither may be used within the literal text ofcode spans andfencedorindentedcode blocks.

For those tags that may contain text with markup, in a Markdowndocumentation comment that markup will also be in Markdown format.

As in traditional documentation comments, the content of inline tagsmay span multiple lines, including blank lines.

When using areferencelink with an explicitlink label,the reference and the label must appear in the same part of the comment:in either the main description, or in any inline or block tag. Areference link may not refer to a label defined in a different part ofthe comment, or in a different comment altogether.

TheinheritDoc tag is used toinclude documentation from one or more supertypes. There is norequirement that the format of the comment containing the tag is thesame as the format of the comment containing the documentation to beinherited. While it may be the case that comments within a library mayall use the same format, that may be less likely when handling commentsin different libraries, written by different authors.

Syntax Highlightingand Embedded Languages

The opening fence in afenced codeblock may be followed by aninfostring, the first word of which is used to derive the CSS classname in the corresponding generated HTML, and which may be used byJavaScript libraries to enable syntax highlighting (such as withPrism) or rendering diagrams (such aswithMermaid).

Note: You can add JavaScript libraries to your documentationby using thejavadoc--add-scriptoption.

Escape Sequences

The following escape sequences are supported in traditionaldocumentation comments wherever text, entities and HTML may appear, torepresent characters that would otherwise be inconvenient or difficultto represent:

Escape sequences are context-sensitive, and can only be used wherethe use of the escaped character by itself would have a differentsyntactic interpretation. In other situations, these character sequencesare taken literally, without additional interpretation.

Escape sequences cannot be used in inline tags that contain literaltext; this includescode,literal,snippet, and user-defined tags.

References

References are the constructs in a documentation comment that referto elements in the surrounding declarations. Depending on the context,they may refer to modules, packages, classes and interfaces,constructors, methods, annotation members, fields, enum members,parameters, record components and the names of exceptions that may bethrown by a method or constructor.

The most general form of a reference is:

This form is used by thesee,link andlinkplain tags.

Leading components can be omitted when they can be inferred from thesurrounding context. Trailing components can be omitted when they arenot required. Generally, the reference is evaluated in the scope inwhich the documentation comment exists. In particular,import statements for the compilation unit are taken intoaccount when evaluating class and interface names.

Theclass may be any top-level or nested class orinterface.

Themember may be any constructor, method, annotationmember, field or enum member, but not a nested class or interface. As inJava source code, a constructor is identified by using the name of itsclass. The name of a constructor or method should normally be followedby the list of its parameter types, enclosed in parentheses, althoughthe parameter types and parentheses can be omitted if the method orconstructor is not overloaded and the name is not also that of a fieldor enum member in the same class or interface. When a parameter list isgiven, whitespace characters may appear between tokens in the parameterlist; whitespace characters may not appear elsewhere in the reference.When the reference is to a member of the same class as that containingthe documentation comment, all parts of the reference up to andincluding the# may be omitted, although the '#' may beretained for clarity.

Parameterized types may be used in the class and member parts of thereference; annotations may not be used anywhere in the reference.Whitespace characters may occur between tokens within the parameter listfor a constructor or method. A trailing/ can be added to aname to refer to a module in the presence of a package or class with thesame name.

Note: You cannot refer to the declaration of a specificparameter or record component with this form.

An alternative form is provided to generate references to arbitraryURI fragments in the generated documentation such as headings indocumentation comments. This form uses a double hash mark(##) as separator:

fragment is interpreted as URI fragment within the pagedocumenting the specified program element.

Other tags, such asparam,throws, andserialField may only providesupport for the specific kinds of references that are relevant to eachtag. See the description of individual tags for more details.

Method Documentation

A documentation comment for a method declaration must at leastprovide the following:

It is an error if any item described in that list is missing from adocumentation comment of a method declaration and either of following istrue:

Otherwise, a missing item is considered as if it were provided with{@inheritDoc} as its content.

For the purpose of this specification an overriding methoddeclaration is a method declaration that could be annotated with@Override (JLS9.6.4.4), but is not an accessor method declaration for a recordcomponent.

Method documentation allows inheritance by omission: if adocumentation comment for a method declaration provides only some of theitems, the rest are assumed to be inherited. For example, if this isprovided:

/** * @param scale a non-zero number * @throws IllegalArgumentException if scale is 0 */ @Override <T> T magnify(int scale, T element) throws MagnificationException

This is assumed:

/** * {@inheritDoc} * * @param <T> {@inheritDoc} * @param scale a non-zero number * @param element {@inheritDoc} * @return {@inheritDoc} * @throws IllegalArgumentException if scale is 0 * @throws MagnificationException {@inheritDoc} */ @Override <T> T magnify(int scale, T element) throws MagnificationException

However, not all missing items can be inherited. For example, if amethod declares an exceptionX that is not documented byany of the methods that this method overrides, then documentation itemfor that exception cannot be inherited and can only be provided by thismethod's documentation comment. (Adding or assuming@throws X {@inheritDoc} would be an error.) If that item isnot provided, it is considered missing.

(@Override is only added to these examples to emphasizethat the declarations are overriding; that annotation has no effect ondocumentation.)

Note: A documentation comment consisting of a soleinheritDoc tag explicitly provides only the maindescription of a method:

/** * {@inheritDoc} */

Other items, if any, are inherited by omission.

Note: It is the overriding method, not the overriddenmethod, that determines which items are missing and which are not.

For example, if an overriding method declares a thrown exceptionX, but that method's documentation comment does not contain@throws X ..., then that documentation item is missing. Ifan overriding method does NOT declare a thrown exception, even if theoverridden method does, then that documentation item is NOT missing.

This behavior is usually noticed when dealing with uncheckedexceptions. Since unchecked exceptions do not normally appear in thethrows clause, unless explicitly documented, they will notbe missing. This gives rise to a misconception that the standard doclettreats checked exceptions differently from unchecked exceptions, whichit does not.

In fact, a similar behavior might be replicated with checkedexceptions. Consider a method that declares two checked exceptionsX andY, such thatX is asupertype ofY. If an overriding method declaresX but notY, then@throws Y ...won't be missing.

Overriding Methodsin Classes and Interfaces

When a method declaration overrides a method in the superclass or anextended superinterface, the standard doclet generates the subheading"Overrides" in the documentation for the overriding method.

When a method declaration in a class overrides a method in aninterface, the standard doclet generates the subheading "Specified by"in the documentation for the overriding method.

In both cases, a link to the overridden method is included.

Standard Tags

The following sections describe the standard block and inline tagssupported by the standard doclet.

Note: The standard doclet also supports user-defined tagsconforming to the same general syntactic rules.

author

Adds an "Author" entry with the specified name text to the generateddocuments when the-author option is used. A documentationcomment can contain multipleauthor tags. You can specifyone name perauthor tag or multiple names per tag. In theformer case, the standard doclet inserts a comma (,) and aspace between names. In the latter case, the entire text is copied tothe generated document without being parsed. Therefore, you can usemultiple names per line if you want a localized name separator otherthan a comma.

If there are noauthor tags in the description for amember class or interface, the standard doclet will (recursively) lookfor any such tags in the enclosing class or interface.

Introduced in JDK 1.0.

code

Equivalent to<code>{@literaltext}</code>.

Displaystext in code font without interpreting the text asHTML markup or nested Javadoc tags. This enables you to use regularangle brackets (< and>) instead of theHTML entities (&lt; and&gt;) indocumentation comments, such as in parameter types(<Object>), inequalities (3 < 4), orarrows (->). For example, the documentation comment text{@code A<B>C} displayed in the generated HTML pageunchanged asA<B>C. This means that the<B> is not interpreted as bold and is in code font.If you want the same functionality without the code font, then use theliteral tag.

Introduced in JDK 1.5.

deprecated

This tag is used in conjunction with the@Deprecatedannotation to indicate that this API should no longer be used (eventhough it may continue to work). The standard doclet moves deprecatedtext ahead of the main description, placing it in italics and precedingit with a bold warning.

The first sentence of deprecated text should tell the user when theAPI was deprecated and what to use as a replacement. The standard docletcopies the first sentence to the summary section and index. Subsequentsentences can also explain why it was deprecated. You should include alink tag that points to the replacement API.

Note:

Introduced in JDK 1.0.

docRoot

Represents the relative path to the generated document's(destination) root directory from any generated page. This tag is usefulwhen you want to include a file, such as a copyright page or companylogo, that you want to reference from all generated pages. Linking tothe copyright page from the bottom of each page is common.

ThedocRoot tag can be used both on the command line andin a documentation comment. The tag is valid in all documentationcomments: overview, module, package, class, interface, constructor,method and field, including the text portion of any tag (such as thereturn,param anddeprecatedtags).

For example, on the command line, where the header, footer, or bottomare defined:

javadoc -bottom '<a href="{@docRoot}/copyright.html">Copyright</a>'.

When you use thedocRoot tag this way in a make file,some makefile programs require a special way to escape for the brace{} characters. For example, the Inprise MAKE version 5.2running on Windows requires double braces:{{@docRoot}}. Italso requires double (rather than single) quotation marks to enclosearguments to options such as the-bottom option (with thequotation marks around thehref argument omitted).

For example, in a documentation comment:

/** * See the <a href="{@docRoot}/copyright.html">Copyright</a>. */

This tag is needed because the generated documents are inhierarchical directories, as deep as the number of subpackages. Theexpression<a href="{@docRoot}/copyright.html">resolves to<a href="../../copyright.html"> forjava/lang/Object.java and<a href="../../../copyright.html"> forjava/lang/ref/Reference.java.

Introduced in JDK 1.3.

exception

This tag is equivalent to thethrows tag, which is now the recommendedform.

Introduced in JDK 1.0.

hidden

Hides a program element from the generated API documentation. Thistag may be used when it is not otherwise possible to design the API in away that such items do not appear at all.

Introduced in JDK 9.

index

Declares that a word or phrase, together with an optional shortdescription, should appear in the index files generated by the standarddoclet. The index entry will be linked to the word or phrase that willappear at this point in the generated documentation. The description maybe used when the word or phrase to be indexed is not clear by itself,such as for an acronym.

Introduced in JDK 9.

inheritDoc

Indicates that a method documentation comment part that contains thistag is the same as that of the overridden method in a superclass orsuperinterface, which is either determined automatically orspecified.

It is an error if the overridden method ismissing the correspondingpart.

This tag enables you to write more general comments higher up theinheritance hierarchy and to write around the inherited parts.

This tag is valid only in these places in a documentation comment ofan overriding declaration of a method:

If the corresponding part of the overridden method's documentationcomment itself uses aninheritDoc tag, then that tag isprocessed first. (This might be applied recursively as required.)

Letm be a method declaration in a class or interfaceT. If the documentation comment form containsaninheritDoc tag then the superclass or superinterface(whose overridden method this tag will use the corresponding part of) isdetermined as follows:

Automatic Supertype Search

The search for the supertype is performed in two phases: therecursive phase, then the final phase. For simplicity, the search startsfromS, whereS = T, although there's nothingto be found inT (otherwise, the search would not berequired). When starting fromS, whereS = T,the first condition always breaks into "otherwise" because a method doesnot override itself (JLS8.4.8.1).

Recursive phase

IfS declares a method thatT.m overrides,thenS is a supertype, otherwise:

IfS is a class that has a direct superclass (JLS8.1.4) that is notjava.lang.Object, then the recursivephase of the search is applied to that superclass. If that applicationhas not found a supertype, then:

IfS has direct superinterfaces (JLS8.1.5), then the recursive phase of the search is applied to each ofthose superinterfaces, in the order that they are listed in theextends (ifS is a class) orimplements (ifS is an interface) clause,until the supertype found or superinterfaces are exhausted.

Final phase

If the recursive phase of search has not found the supertype, thenone final attempt is made to see ifjava.lang.Object is thesupertype. IfT is a class andm overrides amethod injava.lang.Object, orT is aninterface andm's signature is override-equivalent to thesignature of a public method injava.lang.Object (JLS8.4.2), thenjava.lang.Object is the supertype.Otherwise, the search has not found the supertype.

Note: The search is performed in two phases so as to notprematurely considerjava.lang.Object as the supertype.Sometimesjava.lang.Object provides overly generaldocumentation for its public methods (such asequals,hashCode,toString) when more specificdocumentation is available.

For example, consider this schematic hierarchy:

interface Ainterface B extends Ainterface Cclass D implements B, Cinterface Eclass F extends D implements E
    (A)     ^      \      (B) (C)    [java.lang.Object]       ^   ^        \ /        [D] (E)         ^   ^          \ /          [F]
The same hierarchy represented visually.
The automatic supertype search traverses that hierarchy in the followingorder:F,D,B,A,C,E,java.lang.Object.
    (4)     ^      \      (3) (5)    [7]       ^   ^        \ /        [2] (6)         ^   ^          \ /          [1]
The same traversal order represented visually.

Note: The source file for an inherited method must be on thesource path for the documentation comment to be available for copy.Neither the class nor its package needs to be passed in on the commandline.

Note: When usingMarkdown comments, there isno requirement that the comment containing the tag and the commentcontaining the documentation inherited by that tag should either be bothMarkdown documentation comments or both traditional (not Markdown)comments.

Introduced in JDK 1.4; accepts an optional argument since JDK 22.

link

Inserts an inline link with a visible text label that points to thedocumentation for the specified module, package, class, or member nameof a referenced class. This tag is valid in all documentation comments:overview, module, package, class, interface, constructor, method andfield, including the description part of any tag, such as thereturn,param anddeprecatedtags.

This tag is similar to thethird form of thesee tag. The main difference is that thelink tag generates an inline link rather than placing thelink in the "See Also" section. Thelink tag begins andends with braces to separate it from the rest of the inline text. If youneed to use the right brace (}) inside the label, then usethe HTML entity notation&#125;.

There is no limit to the number oflink tags allowed ina sentence.

For example, here is a comment that refers to thegetComponentAt(int, int) method:

Use the {@link #getComponentAt(int, int) getComponentAt} method.

From this code, the standard doclet generates the following HTML(assuming it refers to another class in the same package):

Use the <a href="Component.html#getComponentAt(int,int)">getComponentAt</a> method.

The previous line appears on the web page as:

Use thegetComponentAt method.

Introduced in JDK 1.2.

linkplain

Behaves the same as thelink tag, except the link labelis displayed in plain text rather than code font. Useful when the labelis plain text. For example,

Refer to {@linkplain #add() the overridden method}.

is displayed as:

Refer tothe overridden method.

Introduced in JDK 1.4.

literal

Displays text without interpreting the text as HTML markup or nestedJavadoc tags. This enables you to use angle brackets (<and>) instead of the HTML entities(&lt; and&gt;) in documentationcomments, such as in parameter types (<Object>),inequalities (3 < 4), or arrows (->).For example, the documentation comment text{@literal A<B>C} displays unchanged in the generatedHTML page in your browser, asA<B>C. The<B> is not interpreted as bold (and it is not in codefont). If you want the same functionality with the text in code font,then use thecode tag.

Introduced in JDK 1.5.

param

Adds a parameter with the specified parameter name followed by thespecified description to the "Parameters" section. The description maycontinue onto multiple lines. This tag is valid only in a documentationcomment for a method, constructor, or class. The parameter name can bethe name of a parameter in a method or constructor, or the name of atype parameter of a class, method, or constructor. Use angle brackets(< >) around such a parameter name to indicate theuse of a type parameter.

Example of a type parameter of a class:

/** * @param <E> Type of element stored in a list */public interface List<E> extends Collection<E> { ... }

Example of parameters, including type parameters, of a method:

/** * @param string  the string to be converted * @param type    the type to convert the string to * @param <T>     the type of the element * @param <V>     the value of the element */<T, V extends T> V convert(String string, Class<T> type) { ... }

When aninheritDoc tag is usedin the description of a method formal or type parameter, thecorresponding part of the overridden method documentation is matchedusing the parameter's position, not the parameter's name (JLS8.4.2 andJLS8.4.4).

For example, consider the following method declaration:

/** ... * @param scale a non-zero number ... * @param <T> the type of the element being magnified ... */ <T> T magnify(int scale, T element) throws MagnificationException

Then as far as the documentation inheritance is concerned, these twocomments are equivalent:

/** ... * @param s {@inheritDoc} * @param e {@inheritDoc} ... * @param <E> {@inheritDoc} */ @Override <E> E magnify(int s, E e) throws MagnificationException/** ... * @param scale {@inheritDoc} * @param element {@inheritDoc} ... * @param <T> {@inheritDoc} */ @Override <T> T magnify(int scale, T element) throws MagnificationException

If parameter names differ, care should be taken when inheriting suchparameter documentation because that parameter name might be referred tofrom elsewhere both in the overridden and overriding methods.

Introduced in JDK 1.0.

provides

This tag may only appear in the documentation comment for a moduledeclaration, and serves to document an implementation of a serviceprovided by the module. The description may be used to specify how toobtain an instance of this service provider, and any importantcharacteristics of the provider.

Introduced in JDK 9.

return

As a block tag, adds a "Returns" section with the given description,providing details about the values that may be returned by themethod.

As an inline tag, provides content for the first sentence of amethod's main description, and a "Returns" section, as if"@returndescription" were also present. In thedefault English locale, the first sentence is "Returnsdescription.".

This tag is valid only in a documentation comment for a method. As aninline tag, it may only occur at the beginning of a method's maindescription.

When inheriting documentation, either form of areturntag can be used:

/** * {@return {@inheritDoc}} ... */<T> T magnify(int scale, T element) throws MagnificationException/** ... * @return {@inheritDoc} */ <T> T magnify(int scale, T element) throws MagnificationException

Introduced as a block tag in JDK 1.0, and as an inline tag in JDK16.

see

Adds a "See Also" heading with a link or text entry that points to areference. A documentation comment can contain any number ofsee tags, which are all grouped under the same heading. Thesee tag has three variations. The form to reference otherprogram elements is the most common. This tag is valid in alldocumentation comments. For inserting an inline link within a sentenceto a package, class, or member, use alink tag.

Introduced in JDK 1.0.

serial

Used in the documentation comment for a default serializable field.SeeDocumentingSerializable Fields and Data for a Class.

See also Oracle'sCriteriafor Including Classes in the Serialized Form Specification.

An optional field description should explain the meaning of the fieldand list the acceptable values. When needed, the description can spanmultiple lines. The standard doclet adds this information to theserialized form page.

If a serializable field was added to a class after the class was madeserializable, then a statement should be added to its main descriptionto identify at which version it was added.

Theinclude andexclude arguments identifywhether a class or package should be included or excluded from theserialized form page. They work as follows:

For example, thejavax.swing package is marked with the@serial exclude tag inpackage-info.java. Thepublic classjava.security.BasicPermission is marked withthe@serial exclude tag. The package-private classjava.util.PropertyPermissionCollection is marked with the@serial include tag.

Aserial tag at the class level overrides anyserial tag at the package level.

Introduced in JDK 1.2.

serialData

Uses the data description value to document the types and order ofdata in the serialized form. This data includes the optional datawritten by thewriteObject method and all data (includingbase classes) written by theExternalizable.writeExternalmethod.

TheserialData tag can be used in the documentationcomment for thereadObject,writeObject,readExternal,writeExternal,readResolve, andwriteReplace methods.

Introduced in JDK 1.2.

serialField

Documents anObjectStreamField component of theserialPersistentFields member of aSerializable class. Use oneserialField tagfor eachObjectStreamField component.

Introduced in JDK 1.2.

since

Adds a "Since" heading with the specifiedsince-text valueto the generated documentation. The tag indicates that the associatedprogram element has existed since it was introduced in the softwarerelease specified by thesince-text value. For example,@since 11.

The text has no special internal structure, meaning that commas,whitespace characters and other punctuation have no specialsignificance. Multiplesince tags are allowed; for example,you could use multiple tags when the program element is part of morethan one API. However, when used in conjunction with the feature in thestandard doclet to generate a summary page of what API is new in eachrelease, thesince-text value of the first tag should be asimple string with no formatting markup.

It is recommended that each top-level program element (module,package, class or interface) should contain an appropriatesince tag. In addition, each member element (constructor,method, field, nested class or interface) should have a tag in thosecases where the value is different from that of the enclosing class orinterface. If there are nosince tags in the descriptionfor a member class or interface, the standard doclet will (recursively)look for any such tags in the enclosing class or interface.

Note: One or more methods may be added implicitly to a classor interface as a result of adding additional supertypes in anextends orimplements clause, after the classor interface was first created.

Note: Changing the return type of a method to a covariantreturn type is tantamount to adding a new method with that signature,and should be given an updatedsince tag. This is becausethe method with that new return type could not be called in any priorrelease to leverage that new return type.

Introduced in JDK 1.1.

snippet

Includes a fragment, or "snippet", of example code in the generateddocumentation. The code may be provided inline within the tag byspecifying abodyand/or in anexternal file, specified in theattributes. Within the content,markup tags can be placed in line comments toidentify regions within the text and instruct how to present the text inthese regions.

Additional details about the snippet can be given asattributes, in the form ofname=value pairs, placed after theinitial tag name. An attribute name is always a simple identifier. Anattribute value may be an identifier, unsigned integer, or enclosed ineither single or double quote characters; no escape characters aresupported. An attribute value and the preceding= may beomitted when the presence of the attribute name is sufficient.Attributes are separated from the tag name and from each other bywhitespace characters, such as space and newline.

A snippet may specify anid attribute, which can be usedto identify the snippet in both the API and the generated HTML, andwhich may be used to create a link to the snippet. In the generatedHTML, the id will be placed on the outermost element that is generatedto represent the snippet.

Code fragments are typically Java source code, but they may also befragments of properties files, source code in other languages, or plaintext. A snippet may specify alang attribute, whichidentifies the kind of content in the snippet. For an inline snippet,the default value isjava. For an external or a hybridsnippet, the default value is derived from the extension of the name ofthe file containing the snippet's content.

Inline snippets

An inline snippet contains the content of the snippet within the tagitself.

The content of the snippet, which is included in the generateddocumentation, is the text between the first newline after the colon(:) and the closing curly brace (}).

There is no need to escape characters such as<,>, and& with HTML entities, nor isthere any need to escape documentation comment tags.

Surrounding whitespace is stripped from the content usingString::stripIndent.

There are two limitations on the content of inline snippets:

  1. The character sequence*/ cannot be used anywherewithin the content, because the*/ would terminate theenclosing documentation comment. This includes use of/* ... */ comments, or within a// comment, orwithin string literals, such as those used to represent regularexpressions. This restriction applies to all content in documentationcomments; it is not specific to thesnippet tag.

  2. The content of an inline snippet can only contain balanced pairsof curly-brace characters. The overall inline tag is terminated by thefirst right brace that matches the opening brace. This restrictionapplies to all inline tags; it is not specific to thesnippet tag.

External snippets

An external snippet refers to a separate class or file that containsthe content of the snippet.

In an external snippet the colon, newline, and subsequent content canbe omitted.

Unlike inline snippets, external snippets have no limitations ontheir content. In particular, they may contain/* ... */comments.

The location of the external code can be specified either by classname, using theclass attribute, or by a short relativefile path, using thefile attribute. In either case thefile can be placed in a package hierarchy rooted in asnippet-files subdirectory of the directory containing thesource code with thesnippet tag. Alternatively, the filecan be placed on an auxiliary search path, specified by the--snippet-path option to thejavadoc tool. Theuse ofsnippet-files subdirectories is similar to the useofdoc-files subdirectories for auxiliary documentationfiles.

The file for an external snippet may contain multiple regions, to bereferenced in different snippet tags, appearing in different parts ofthe documentation.

Hybrid snippets

A hybrid snippet is both an internal snippet and an external snippet.It contains the content of the snippet within the tag itself, for theconvenience of anyone reading the source code for the class beingdocumented, and it also refers to a separate file that contains thecontent of the snippet.

It is an error if the result of processing a hybrid snippet as aninline snippet does not match the result of processing it as an externalsnippet.

Markup tags

Markup tags define regions within the content of a snippet. They alsocontrol the presentation of the content, for example highlighting partsof the text, modifying the text, or linking to elsewhere in thedocumentation. They can be used in internal, external, and hybridsnippets.

Markup tags begin with@name, followed by anyrequired arguments. They are placed in// comments (or theequivalent in other languages or formats), so as not to unduly interferewith the body of the source code, and also because/* ... */ comments cannot be used in inline snippets. Suchcomments are referred to asmarkup comments.

Multiple markup tags can be placed in the same markup comment. Themarkup tags apply to the source line containing the comment unless thecomment is terminated with a colon (:), in which case it isas if the tags were present on the immediately following line. Thelatter syntax may be useful if the markup comment is particularly long,or if the syntactic format of the content of a snippet does not permitcomments to appear on the same line as non-comment source. Markupcomments do not appear in the generated output.

Because some other systems use meta-comments similar to markupcomments, comments that begin with@ followed by anunrecognized name are ignored as markup comments and will appear in thegenerated output. If the name is recognized, but there are subsequenterrors in the markup comment, then an error is reported. The generatedoutput in such cases is undefined, with respect to the output generatedfrom the snippet.

Regions

A region is an optionally-named range of lines that identifies thetext to be displayed by a snippet. They also define the scope of actionssuch as highlighting or modifying the text.

The beginning of a region is marked by either

The end of a region is marked by@end or@end region=name. If a name is given then the tagends the region started with that name. If no name is given then the tagends the most recently started region that does not already have amatching@end tag.

There are no constraints on the regions created by different pairs ofmatching@start and@end tags. Regions caneven overlap, although we do not expect such usage to be common.

Highlighting

To highlight content on a line or in a range of lines, use@highlight followed by arguments that specify the scope ofthe text to be considered, the text within that scope to be highlighted,and the type of the highlighting.

Ifregion orregion=name isspecified then the scope is that region, up to the corresponding@end tag. Otherwise, the scope is just the currentline.

To highlight each instance of a literal string within the scope,specify the string withsubstring=string wherestring can be an identifier or text enclosed in single ordouble quotes. To highlight each instance of text matched by a regularexpression within the scope, useregex=string. Ifneither of these attributes are specified then the entire scope ishighlighted.

The type of highlighting can be specified with thetypeparameter. Valid type names arebold,italic,andhighlighted. The name of the type is converted to a CSSclass name whose properties can be defined in the system stylesheet oroverridden in a user-defined stylesheet.

Modifying the displayed text

It is often convenient to write the content of a snippet as code thatcan be accessed and validated by external tools, but to display it in aform that does not compile. For example, it may be desirable to includeimport statements for illustrative purposes along with codethat uses the imported types. Or, it may be desirable to display codewith an ellipsis or some other marker to indicate that additional codeshould be inserted at that point. This can be done by replacing parts ofthe content of the snippet with some replacement text.

To replace some text with replacement text, use@replacefollowed by arguments that specify the scope of the text to beconsidered, the text within that scope to be replaced, and thereplacement text.

Ifregion orregion=name isspecified then the scope is that region, up to the corresponding@end tag. Otherwise, the scope is just the currentline.

To replace each instance of a literal string within the scope,specify the string withsubstring=string wherestring can be an identifier or text enclosed in single ordouble quotes. To replace each instance of text matched by a regularexpression within the scope, useregex=string. Ifneither of these attributes are specified then the entire scope isreplaced.

Specify the replacement text with thereplacementparameter. If a regular expression is used to specify the text to bereplaced then$number or$name can be used to substitute groups found inthe regular expression, as defined byString::replaceAll.

To delete text, use@replace with an empty replacementstring. To insert text, use@replace to replace some no-optext placed where the replacement text should be inserted. The no-optext might be a '//' marker, or an empty statement (;).

Linking text

To link text to declarations elsewhere in the API, use@link followed by arguments that specify the scope of thetext to be considered, the text within that scope to be linked, and thetarget of the link.

Ifregion orregion=name isspecified then the scope is that region, up to the corresponding@end tag. Otherwise, the scope is just the currentline.

To link each instance of a literal string within the scope, specifythe string withsubstring=string wherestring can be an identifier or text enclosed in single ordouble quotes. To link each instance of text matched by a regularexpression within the scope, useregex=string. Ifneither of these attributes are specified then the entire scope islinked.

Specify the target with thetarget parameter. The formof its value is the same as used by the standard inlinelink tag.

Introduced in JDK 18.

spec

Identifies an external specification in terms of its URL and title.The URL may be absolute or relative. Relative URLs will be evaluatedagainst a "base URL".

All tags specifying the same URL must provide the same correspondingtitle; conversely, tags with different URLs must have differenttitles.

Introduced in JDK 20.

summary

Identify the summary of an API description, as an alternative to thedefault policy to identify and use the first sentence of the APIdescription. The tag only has significance when used at the beginning ofa main description. In all cases, the tag is rendered by simplyrendering its content.

Introduced in JDK 10.

systemProperty

Identifyproperty-name as the name of a system property. Thename should be a "dotted identifier". In particular, it must not containwhitespace characters, or characters such as}. No othercontent is permitted in the tag; the possibility of additional contentis reserved for future use. The tag can be used in all documentationcomments.

Introduced in JDK 12.

throws

Adds an exception with the specified name followed by the specifieddescription to the "Throws" section of a Method or Constructordetail.

exception-name shouldrefer to anexception that might be thrown by the method, and should either be thename of an exception class or a type variable. This tag is valid only inthe documentation comment for a method or constructor.

A documentation comment may use multiplethrows tags forthe same or different exceptions. If such a comment is then targeted byaninheritDoc tag, it copies all exceptions of that kindinto the "Throws" section.

Note: An unchecked exception class may be omitted from thethrows clause, and so won't be considered missing in amethod documentation. To inherit a description of such an exception, adda correspondingthrows tag with aninheritDoctag in its description.

To ensure that all checked exceptions are documented, when athrows tag does not exist for an exception in thethrows clause, the standard doclet adds that exception tothe generated output (with no description) as if it were documented withthethrows tag.

Theexception tag is equivalentto this tag, although using athrows tag is nowrecommended.

Introduced in JDK 1.2.

uses

This tag may only appear in the documentation comment for a moduledeclaration, and serves to document that a service may be used by themodule. The description may be used to specify the characteristics ofthe service that may be required, and what the module will do if noprovider for the service is available.

Introduced in JDK 9.

value

Displays the value of a static field with a compile-time constantvalue.

The format string may be omitted, in which case a default format willbe used, appropriate to the type of the field. If the format string isgiven, it must either begin with a percent character (%) orbe enclosed in double-quote characters ("). It must containexactly one percent character. The string must conform to the definitionof a format string, as specified in the documentation forjava.util.Formatter.The conversion specified in the format string must be appropriate forthe type of the constant value.

When thevalue tag is used without afield_reference argument in the documentation comment of astatic field, it displays the value of that constant:

/** * The value of this constant is {@value}. */public static final String SCRIPT_START = "<script>"

When used with afield-referenceargument in any documentation comment, thevalue tagdisplays the value of the specified constant:

/** * Evaluates the script starting with {@value #SCRIPT_START}. */public String evalScript(String script) {}

Introduced in JDK 1.4;format added in JDK 20.

version

Adds a "Version" subheading with the specifiedversion-textvalue to the generated documents when the -version option is used. Thistag is intended to hold the current release number of the software thatthis code is part of, as opposed to thesince tag, whichholds the release number where this code was introduced. Theversion-text value has no special internal structure.

A documentation comment can contain multipleversiontags. When it makes sense, you can specify one release number perversion tag or multiple release numbers per tag. In theformer case, the standard doclet inserts a comma (,) and aspace between the names. In the latter case, the entire text is copiedto the generated document without being parsed. Therefore, you can usemultiple names per line when you want a localized separator other than acomma.

If there are noversion tags in the description for amember class or interface, the standard doclet will (recursively) lookfor any such tags in the enclosing class or interface.

Introduced in JDK 1.0.

Where Tags Can Be Used

The following table summarizes which tags can be used in whichcontexts.

Contexts in which tags may be used
TagModulePackageTypeConstructorMethodFieldOther
author✓✓✓✓
code✓✓✓✓✓✓✓
deprecated✓✓✓✓✓
docRoot✓✓✓✓✓✓✓
exception✓✓
hidden✓✓✓
index✓✓✓✓✓✓✓
inheritDoc✓
link✓✓✓✓✓✓✓
linkplain✓✓✓✓✓✓✓
literal✓✓✓✓✓✓✓
param✓✓✓
provides✓
return✓
see✓✓✓✓✓✓✓
serial✓✓✓
serialData*
serialField*
since✓✓✓✓✓✓✓
snippet✓✓✓✓✓✓✓
summary✓✓✓✓✓✓✓
systemProperty✓✓✓✓✓✓✓
throws✓✓
uses✓
value✓✓✓✓✓✓✓
version✓✓✓✓

Notes:

[8]ページ先頭
©2009-2025 Movatter.jp