1/* 2 * Copyright (c) 1998, 2017, Oracle and/or its affiliates. All rights reserved. 3 * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER. 4 * 5 * This code is free software; you can redistribute it and/or modify it 6 * under the terms of the GNU General Public License version 2 only, as 7 * published by the Free Software Foundation. Oracle designates this 8 * particular file as subject to the "Classpath" exception as provided 9 * by Oracle in the LICENSE file that accompanied this code. 10 * 11 * This code is distributed in the hope that it will be useful, but WITHOUT 12 * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or 13 * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License 14 * version 2 for more details (a copy is included in the LICENSE file that 15 * accompanied this code). 16 * 17 * You should have received a copy of the GNU General Public License version 18 * 2 along with this work; if not, write to the Free Software Foundation, 19 * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA. 20 * 21 * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA 22 * or visit www.oracle.com if you need additional information or have any 23 * questions. 24 */ 25 26package com.sun.javadoc; 27 28import java.text.BreakIterator; 29import java.util.Locale; 30 31/** 32 * Represents a simple documentation tag, such as @since, @author, @version. 33 * Given a tag (e.g. "@since 1.2"), holds tag name (e.g. "@since") 34 * and tag text (e.g. "1.2"). Tags with structure or which require 35 * special processing are handled by subclasses such as ParamTag 36 * (for @param), SeeTag (for @see and {@link}), and ThrowsTag 37 * (for @throws). 38 * 39 * @author Robert Field 40 * @author Atul M Dambalkar 41 * @see SeeTag 42 * @see ParamTag 43 * @see ThrowsTag 44 * @see SerialFieldTag 45 * @see Doc#tags() 46 * 47 * @deprecated 48 * The declarations in this package have been superseded by those 49 * in the package {@code jdk.javadoc.doclet}. 50 * For more information, see the <i>Migration Guide</i> in the documentation for that package. 51 */ 52@Deprecated 53public interface Tag { 54 55 /** 56 * Return the name of this tag. The name is the string 57 * starting with "@" that is used in a doc comment, such as 58 * {@code @return}. For inline tags, such as 59 * {@code {@link}}, the curly brackets 60 * are not part of the name, so in this example the name 61 * would be simply {@code @link}. 62 * 63 * @return the name of this tag 64 */ 65 String name(); 66 67 /** 68 * Return the containing {@link Doc} of this Tag element. 69 * 70 * @return the containing {@link Doc} of this Tag element 71 */ 72 Doc holder(); 73 74 /** 75 * Return the kind of this tag. 76 * For most tags, 77 * {@code kind() == name()}; 78 * the following table lists those cases where there is more 79 * than one tag of a given kind: 80 * 81 * <table class="striped"> 82 * <caption>Related Tags</caption> 83 * <thead> 84 * <tr><th scope="col">{@code name() } <th scope="col">{@code kind() } 85 * </thead> 86 * <tbody style="text-align:left"> 87 * <tr><th scope="row">{@code @exception } <td>{@code @throws } 88 * <tr><th scope="row">{@code @link } <td>{@code @see } 89 * <tr><th scope="row">{@code @linkplain } <td>{@code @see } 90 * <tr><th scope="row">{@code @see } <td>{@code @see } 91 * <tr><th scope="row">{@code @serial } <td>{@code @serial } 92 * <tr><th scope="row">{@code @serialData } <td>{@code @serial } 93 * <tr><th scope="row">{@code @throws } <td>{@code @throws } 94 * </tbody> 95 * </table> 96 * 97 * @return the kind of this tag. 98 */ 99 String kind(); 100 101 /** 102 * Return the text of this tag, that is, the portion beyond tag name. 103 * 104 * @return the text of this tag 105 */ 106 String text(); 107 108 /** 109 * Convert this object to a string. 110 */ 111 String toString(); 112 113 /** 114 * For a documentation comment with embedded {@code {@link}} 115 * tags, return an array of {@code Tag} objects. The entire 116 * doc comment is broken down into strings separated by 117 * {@code {@link}} tags, where each successive element 118 * of the array represents either a string or 119 * {@code {@link}} tag, in order, from start to end. 120 * Each string is represented by a {@code Tag} object of 121 * name "Text", where {@link #text()} returns the string. Each 122 * {@code {@link}} tag is represented by a 123 * {@link SeeTag} of name "@link" and kind "@see". 124 * For example, given the following comment 125 * tag: 126 * <p> 127 * {@code This is a {@link Doc commentlabel} example.} 128 * <p> 129 * return an array of Tag objects: 130 * <ul> 131 * <li> tags[0] is a {@link Tag} with name "Text" and text consisting 132 * of "This is a " 133 * <li> tags[1] is a {@link SeeTag} with name "@link", referenced 134 * class {@code Doc} and label "commentlabel" 135 * <li> tags[2] is a {@link Tag} with name "Text" and text consisting 136 * of " example." 137 * </ul> 138 * 139 * @return Tag[] array of tags 140 * @see ParamTag 141 * @see ThrowsTag 142 */ 143 Tag[] inlineTags(); 144 145 /** 146 * Return the first sentence of the comment as an array of tags. 147 * Includes inline tags 148 * (i.e. {@link <i>reference</i>} tags) but not 149 * block tags. 150 * Each section of plain text is represented as a {@link Tag} 151 * of kind "Text". 152 * Inline tags are represented as a {@link SeeTag} of kind "@link". 153 * If the locale is English language, the first sentence is 154 * determined by the rules described in the Java Language 155 * Specification (first version): "This sentence ends 156 * at the first period that is followed by a blank, tab, or 157 * line terminator or at the first tagline.", in 158 * addition a line will be terminated by paragraph and 159 * section terminating HTML tags: <p> </p> <h1> 160 * <h2> <h3> <h4> <h5> <h6> 161 * <hr> <pre> or </pre>. 162 * If the locale is not English, the sentence end will be 163 * determined by 164 * {@link BreakIterator#getSentenceInstance(Locale)}. 165 * 166 * @return an array of {@link Tag} objects representing the 167 * first sentence of the comment 168 */ 169 Tag[] firstSentenceTags(); 170 171 /** 172 * Return the source position of this tag. 173 * @return the source position of this tag. 174 */ 175 public SourcePosition position(); 176} 177