src/jdk.javadoc/share/classes/com/sun/javadoc/SeeTag.java
branchniosocketimpl-branch
changeset 57208 7a45c67e73d0
parent 57207 30695f27d7ea
parent 53902 7a6fd71449e7
child 57210 a67ea4f53e56
equal deleted inserted replaced
57207:30695f27d7ea 57208:7a45c67e73d0
     1 /*
       
     2  * Copyright (c) 1998, 2018, 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 
       
    26 package com.sun.javadoc;
       
    27 
       
    28 /**
       
    29  * Represents a user-defined cross-reference to related documentation.
       
    30  * The tag can reference a package, class or member, or can hold
       
    31  * plain text.  (The plain text might be a reference
       
    32  * to something not online, such as a printed book, or be a hard-coded
       
    33  * HTML link.)  The reference can either be inline with the comment,
       
    34  * using {@code {@link}}, or a separate block comment,
       
    35  * using {@code @see}.
       
    36  * Method {@code name()} returns "@link" (no curly braces) or
       
    37  * "@see", depending on the tag.
       
    38  * Method {@code kind()} returns "@see" for both tags.
       
    39  *
       
    40  * @author Kaiyang Liu (original)
       
    41  * @author Robert Field (rewrite)
       
    42  * @author Atul M Dambalkar
       
    43  *
       
    44  * @deprecated
       
    45  *   The declarations in this package have been superseded by those
       
    46  *   in the package {@code jdk.javadoc.doclet}.
       
    47  *   For more information, see the <i>Migration Guide</i> in the documentation for that package.
       
    48  */
       
    49 @Deprecated(since="9", forRemoval=true)
       
    50 @SuppressWarnings("removal")
       
    51 public interface SeeTag extends Tag {
       
    52 
       
    53     /**
       
    54      * Get the label of the {@code @see} tag.
       
    55      * Return null if no label is present.
       
    56      * For example, for:
       
    57      * <p>
       
    58      *    &nbsp;&nbsp;{@code @see String#trim() the trim method}
       
    59      * </p>
       
    60      * return "the trim method".
       
    61      *
       
    62      * @return "the trim method".
       
    63      */
       
    64     String label();
       
    65 
       
    66     /**
       
    67      * Get the package doc when {@code @see} references only a package.
       
    68      * Return null if the package cannot be found, or if
       
    69      * {@code @see} references any other element (class,
       
    70      * interface, field, constructor, method) or non-element.
       
    71      * For example, for:
       
    72      * <p>
       
    73      *   &nbsp;&nbsp;{@code @see java.lang}
       
    74      * </p>
       
    75      * return the {@code PackageDoc} for {@code java.lang}.
       
    76      *
       
    77      * @return the {@code PackageDoc} for {@code java.lang}.
       
    78      */
       
    79     public PackageDoc referencedPackage();
       
    80 
       
    81     /**
       
    82      * Get the class or interface name of the {@code @see} reference.
       
    83      * The name is fully qualified if the name specified in the
       
    84      * original {@code @see} tag was fully qualified, or if the class
       
    85      * or interface can be found; otherwise it is unqualified.
       
    86      * If {@code @see} references only a package name, then return
       
    87      * the package name instead.
       
    88      * For example, for:
       
    89      * <p>
       
    90      *   &nbsp;&nbsp;{@code @see String#valueOf(java.lang.Object)}
       
    91      * </p>
       
    92      * return "java.lang.String".
       
    93      * For "{@code @see java.lang}", return "java.lang".
       
    94      * Return null if {@code @see} references a non-element, such as
       
    95      * {@code @see <a href="java.sun.com">}.
       
    96      *
       
    97      * @return null if {@code @see} references a non-element, such as
       
    98      * {@code @see <a href="java.sun.com">}.
       
    99      */
       
   100     String referencedClassName();
       
   101 
       
   102     /**
       
   103      * Get the class doc referenced by the class name part of @see.
       
   104      * Return null if the class cannot be found.
       
   105      * For example, for:
       
   106      * <p>
       
   107      *   &nbsp;&nbsp;{@code @see String#valueOf(java.lang.Object)}
       
   108      * </p>
       
   109      * return the {@code ClassDoc} for {@code java.lang.String}.
       
   110      *
       
   111      * @return the {@code ClassDoc} for {@code java.lang.String}.
       
   112      */
       
   113     ClassDoc referencedClass();
       
   114 
       
   115     /**
       
   116      * Get the field, constructor or method substring of the {@code @see}
       
   117      * reference. Return null if the reference is to any other
       
   118      * element or to any non-element.
       
   119      * References to member classes (nested classes) return null.
       
   120      * For example, for:
       
   121      * <p>
       
   122      *   &nbsp;&nbsp;{@code @see String#startsWith(String)}
       
   123      * </p>
       
   124      * return "startsWith(String)".
       
   125      *
       
   126      * @return "startsWith(String)".
       
   127      */
       
   128     String referencedMemberName();
       
   129 
       
   130     /**
       
   131      * Get the member doc for the field, constructor or method
       
   132      * referenced by {@code @see}. Return null if the member cannot
       
   133      * be found or if the reference is to any other element or to any
       
   134      * non-element.
       
   135      * References to member classes (nested classes) return null.
       
   136      * For example, for:
       
   137      * <p>
       
   138      *   &nbsp;&nbsp;{@code @see String#startsWith(java.lang.String)}
       
   139      * </p>
       
   140      * return the {@code MethodDoc} for {@code startsWith}.
       
   141      *
       
   142      * @return the {@code MethodDoc} for {@code startsWith}.
       
   143      */
       
   144     MemberDoc referencedMember();
       
   145 }