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

duke@1: * This is a {@link Doc commentlabel} example. duke@1: *

duke@1: * return an array of Tag objects: duke@1: *

duke@1: * duke@1: * @return Tag[] array of tags duke@1: * @see ParamTag duke@1: * @see ThrowsTag duke@1: */ duke@1: Tag[] inlineTags(); duke@1: duke@1: /** duke@1: * Return the first sentence of the comment as an array of tags. duke@1: * Includes inline tags jjg@1326: * (i.e. {@link reference} tags) but not duke@1: * block tags. duke@1: * Each section of plain text is represented as a {@link Tag} duke@1: * of kind "Text". duke@1: * Inline tags are represented as a {@link SeeTag} of kind "@link". duke@1: * If the locale is English language, the first sentence is duke@1: * determined by the rules described in the Java Language duke@1: * Specification (first version): "This sentence ends duke@1: * at the first period that is followed by a blank, tab, or duke@1: * line terminator or at the first tagline.", in duke@1: * addition a line will be terminated by paragraph and duke@1: * section terminating HTML tags: <p> </p> <h1> duke@1: * <h2> <h3> <h4> <h5> <h6> duke@1: * <hr> <pre> or </pre>. duke@1: * If the locale is not English, the sentence end will be duke@1: * determined by duke@1: * {@link BreakIterator#getSentenceInstance(Locale)}. duke@1: * duke@1: * @return an array of {@link Tag} objects representing the duke@1: * first sentence of the comment duke@1: */ duke@1: Tag[] firstSentenceTags(); duke@1: duke@1: /** duke@1: * Return the source position of this tag. duke@1: * @return the source position of this tag. duke@1: */ duke@1: public SourcePosition position(); duke@1: }