InheritDocTaglet.java revision 3233:b5d08bc0d224
1/* 2 * Copyright (c) 2001, 2016, 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 jdk.javadoc.internal.doclets.toolkit.taglets; 27 28import javax.lang.model.element.Element; 29import javax.lang.model.element.ExecutableElement; 30 31import com.sun.source.doctree.DocTree; 32import jdk.javadoc.internal.doclets.toolkit.Configuration; 33import jdk.javadoc.internal.doclets.toolkit.Content; 34import jdk.javadoc.internal.doclets.toolkit.util.CommentHelper; 35import jdk.javadoc.internal.doclets.toolkit.util.DocFinder; 36import jdk.javadoc.internal.doclets.toolkit.util.DocFinder.Input; 37import jdk.javadoc.internal.doclets.toolkit.util.Utils; 38 39import static com.sun.source.doctree.DocTree.Kind.*; 40 41/** 42 * An inline Taglet representing the <b>inheritDoc</b> tag. This tag should only 43 * be used with a method. It is used to inherit documentation from overriden 44 * and implemented methods. 45 * 46 * <p><b>This is NOT part of any supported API. 47 * If you write code that depends on this, you do so at your own risk. 48 * This code and its internal interfaces are subject to change or 49 * deletion without notice.</b> 50 * 51 * @author Jamie Ho 52 */ 53 54public class InheritDocTaglet extends BaseInlineTaglet { 55 56 /** 57 * The inline tag that would appear in the documentation if 58 * the writer wanted documentation to be inherited. 59 */ 60 public static final String INHERIT_DOC_INLINE_TAG = "{@inheritDoc}"; 61 62 /** 63 * Construct a new InheritDocTaglet. 64 */ 65 public InheritDocTaglet () { 66 name = INHERIT_DOC.tagName; 67 } 68 69 /** 70 * Will return false because this inline tag may 71 * not appear in Fields. 72 * @return false 73 */ 74 public boolean inField() { 75 return false; 76 } 77 78 /** 79 * Will return false because this inline tag may 80 * not appear in Constructors. 81 * @return false 82 */ 83 public boolean inConstructor() { 84 return false; 85 } 86 87 /** 88 * Will return false because this inline tag may 89 * not appear in Overview. 90 * @return false 91 */ 92 public boolean inOverview() { 93 return false; 94 } 95 96 /** 97 * Will return false because this inline tag may 98 * not appear in Packages. 99 * @return false 100 */ 101 public boolean inPackage() { 102 return false; 103 } 104 105 /** 106 * Will return true because this inline tag may 107 * appear in Type (Class). 108 * @return true 109 */ 110 public boolean inType() { 111 return true; 112 } 113 114 /** 115 * Given a <code>MethodDoc</code> item, a <code>Tag</code> in the 116 * <code>MethodDoc</code> item and a String, replace all occurrences 117 * of @inheritDoc with documentation from it's superclass or superinterface. 118 * 119 * @param writer the writer that is writing the output. 120 * @param e the {@link Element} that we are documenting. 121 * @param holderTag the tag that holds the inheritDoc tag or null for type 122 * (class) docs. 123 * @param isFirstSentence true if we only want to inherit the first sentence. 124 */ 125 private Content retrieveInheritedDocumentation(TagletWriter writer, 126 Element e, DocTree holderTag, boolean isFirstSentence) { 127 Content replacement = writer.getOutputInstance(); 128 Configuration configuration = writer.configuration(); 129 Utils utils = configuration.utils; 130 CommentHelper ch = utils.getCommentHelper(e); 131 Taglet inheritableTaglet = holderTag == null 132 ? null 133 : configuration.tagletManager.getTaglet(ch.getTagName(holderTag)); 134 if (inheritableTaglet != null && 135 !(inheritableTaglet instanceof InheritableTaglet)) { 136 String message = utils.getSimpleName(e) + 137 ((utils.isExecutableElement(e)) 138 ? utils.flatSignature((ExecutableElement)e) 139 : ""); 140 //This tag does not support inheritence. 141 configuration.message.warning(e, "doclet.noInheritedDoc", message); 142 } 143 Input input = new DocFinder.Input(utils, e, 144 (InheritableTaglet) inheritableTaglet, new DocFinder.DocTreeInfo(holderTag, e), 145 isFirstSentence, true); 146 DocFinder.Output inheritedDoc = DocFinder.search(configuration, input); 147 if (inheritedDoc.isValidInheritDocTag) { 148 if (!inheritedDoc.inlineTags.isEmpty()) { 149 replacement = writer.commentTagsToOutput(inheritedDoc.holderTag, 150 inheritedDoc.holder, inheritedDoc.inlineTags, isFirstSentence); 151 ch.setOverrideElement(inheritedDoc.holder); 152 } 153 154 } else { 155 String message = utils.getSimpleName(e) + 156 ((utils.isExecutableElement(e)) 157 ? utils.flatSignature((ExecutableElement)e) 158 : ""); 159 configuration.message.warning(e, "doclet.noInheritedDoc", message); 160 } 161 return replacement; 162 } 163 164 /** 165 * Given the <code>Tag</code> representation of this custom 166 * tag, return its string representation, which is output 167 * to the generated page. 168 * 169 * @param e the element holding the tag 170 * @param tag the <code>Tag</code> representation of this custom tag. 171 * @param tagletWriter the taglet writer for output. 172 * @return the Content representation of this <code>Tag</code>. 173 */ 174 public Content getTagletOutput(Element e, DocTree tag, TagletWriter tagletWriter) { 175 DocTree inheritTag = tag.getKind() == INHERIT_DOC ? null : tag; 176 return retrieveInheritedDocumentation(tagletWriter, e, 177 inheritTag, tagletWriter.isFirstSentence); 178 } 179} 180