/*
* Copyright (c) 1998, 2013, Oracle and/or its affiliates. All rights reserved.
* DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
*
* This code is free software; you can redistribute it and/or modify it
* under the terms of the GNU General Public License version 2 only, as
* published by the Free Software Foundation. Oracle designates this
* particular file as subject to the "Classpath" exception as provided
* by Oracle in the LICENSE file that accompanied this code.
*
* This code is distributed in the hope that it will be useful, but WITHOUT
* ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
* FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
* version 2 for more details (a copy is included in the LICENSE file that
* accompanied this code).
*
* You should have received a copy of the GNU General Public License version
* 2 along with this work; if not, write to the Free Software Foundation,
* Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
*
* Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
* or visit www.oracle.com if you need additional information or have any
* questions.
*/
package com.sun.javadoc;
import java.text.BreakIterator;
import java.util.Locale;
/**
* Represents a simple documentation tag, such as @since, @author, @version.
* Given a tag (e.g. "@since 1.2"), holds tag name (e.g. "@since")
* and tag text (e.g. "1.2"). Tags with structure or which require
* special processing are handled by subclasses such as ParamTag
* (for @param), SeeTag (for @see and {@link}), and ThrowsTag
* (for @throws).
*
* @author Robert Field
* @author Atul M Dambalkar
* @see SeeTag
* @see ParamTag
* @see ThrowsTag
* @see SerialFieldTag
* @see Doc#tags()
*
*/
public interface Tag {
/**
* Return the name of this tag. The name is the string
* starting with "@" that is used in a doc comment, such as
* @return
. For inline tags, such as
* {@link}
, the curly brackets
* are not part of the name, so in this example the name
* would be simply @link
.
*
* @return the name of this tag
*/
String name();
/**
* Return the containing {@link Doc} of this Tag element.
*
* @return the containing {@link Doc} of this Tag element
*/
Doc holder();
/**
* Return the kind of this tag.
* For most tags,
* kind() == name()
;
* the following table lists those cases where there is more
* than one tag of a given kind:
*
*
{@code kind() } | {@code name() } |
---|---|
{@code @throws } | {@code @throws } |
{@code @throws } | {@code @exception } |
{@code @see } | {@code @see } |
{@code @see } | {@code @link } |
{@code @see } | {@code @linkplain } |
{@code @serial } | {@code @serial } |
{@code @serial } | {@code @serialData } |
{@link}
* tags, return an array of Tag
objects. The entire
* doc comment is broken down into strings separated by
* {@link}
tags, where each successive element
* of the array represents either a string or
* {@link}
tag, in order, from start to end.
* Each string is represented by a Tag
object of
* name "Text", where {@link #text()} returns the string. Each
* {@link}
tag is represented by a
* {@link SeeTag} of name "@link" and kind "@see".
* For example, given the following comment
* tag:
*
* This is a {@link Doc commentlabel} example.
*
* return an array of Tag objects: *
Doc
and label "commentlabel"
*