1 /* 2 * Copyright (c) 1997, 2019, 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 jdk.javadoc.internal.doclets.formats.html; 27 28 import java.util.*; 29 30 import javax.lang.model.element.Element; 31 import javax.lang.model.element.TypeElement; 32 33 import com.sun.source.doctree.DocTree; 34 import jdk.javadoc.internal.doclets.formats.html.markup.HtmlStyle; 35 import jdk.javadoc.internal.doclets.formats.html.markup.HtmlTag; 36 import jdk.javadoc.internal.doclets.formats.html.markup.HtmlTree; 37 import jdk.javadoc.internal.doclets.toolkit.Content; 38 import jdk.javadoc.internal.doclets.toolkit.util.DocPath; 39 40 /** 41 * This abstract class exists to provide functionality needed in the 42 * the formatting of member information. Since AbstractSubWriter and its 43 * subclasses control this, they would be the logical place to put this. 44 * However, because each member type has its own subclass, subclassing 45 * can not be used effectively to change formatting. The concrete 46 * class subclass of this class can be subclassed to change formatting. 47 * 48 * <p><b>This is NOT part of any supported API. 49 * If you write code that depends on this, you do so at your own risk. 50 * This code and its internal interfaces are subject to change or 51 * deletion without notice.</b> 52 * 53 * @see AbstractMemberWriter 54 * @see ClassWriterImpl 55 * 56 * @author Robert Field 57 * @author Atul M Dambalkar 58 * @author Bhavesh Patel (Modified) 59 */ 60 public abstract class SubWriterHolderWriter extends HtmlDocletWriter { 61 62 /** 63 * The HTML tree for main tag. 64 */ 65 protected HtmlTree mainTree = HtmlTree.MAIN(); 66 SubWriterHolderWriter(HtmlConfiguration configuration, DocPath filename)67 public SubWriterHolderWriter(HtmlConfiguration configuration, DocPath filename) { 68 super(configuration, filename); 69 } 70 71 /** 72 * Add the summary header. 73 * 74 * @param mw the writer for the member being documented 75 * @param typeElement the type element to be documented 76 * @param memberTree the content tree to which the summary header will be added 77 */ addSummaryHeader(AbstractMemberWriter mw, TypeElement typeElement, Content memberTree)78 public void addSummaryHeader(AbstractMemberWriter mw, TypeElement typeElement, 79 Content memberTree) { 80 mw.addSummaryAnchor(typeElement, memberTree); 81 mw.addSummaryLabel(memberTree); 82 } 83 84 /** 85 * Add the inherited summary header. 86 * 87 * @param mw the writer for the member being documented 88 * @param typeElement the te to be documented 89 * @param inheritedTree the content tree to which the inherited summary header will be added 90 */ addInheritedSummaryHeader(AbstractMemberWriter mw, TypeElement typeElement, Content inheritedTree)91 public void addInheritedSummaryHeader(AbstractMemberWriter mw, TypeElement typeElement, 92 Content inheritedTree) { 93 mw.addInheritedSummaryLabel(typeElement, inheritedTree); 94 mw.addInheritedSummaryAnchor(typeElement, inheritedTree); 95 } 96 97 /** 98 * Add the index comment. 99 * 100 * @param member the member being documented 101 * @param contentTree the content tree to which the comment will be added 102 */ addIndexComment(Element member, Content contentTree)103 protected void addIndexComment(Element member, Content contentTree) { 104 List<? extends DocTree> tags = utils.getFirstSentenceTrees(member); 105 addIndexComment(member, tags, contentTree); 106 } 107 108 /** 109 * Add the index comment. 110 * 111 * @param member the member being documented 112 * @param firstSentenceTags the first sentence tags for the member to be documented 113 * @param tdSummary the content tree to which the comment will be added 114 */ addIndexComment(Element member, List<? extends DocTree> firstSentenceTags, Content tdSummary)115 protected void addIndexComment(Element member, List<? extends DocTree> firstSentenceTags, 116 Content tdSummary) { 117 List<? extends DocTree> deprs = utils.getBlockTags(member, DocTree.Kind.DEPRECATED); 118 Content div; 119 if (utils.isDeprecated(member)) { 120 Content deprLabel = HtmlTree.SPAN(HtmlStyle.deprecatedLabel, getDeprecatedPhrase(member)); 121 div = HtmlTree.DIV(HtmlStyle.block, deprLabel); 122 if (!deprs.isEmpty()) { 123 addSummaryDeprecatedComment(member, deprs.get(0), div); 124 } 125 tdSummary.add(div); 126 return; 127 } else { 128 Element te = member.getEnclosingElement(); 129 if (te != null && utils.isTypeElement(te) && utils.isDeprecated(te)) { 130 Content deprLabel = HtmlTree.SPAN(HtmlStyle.deprecatedLabel, getDeprecatedPhrase(te)); 131 div = HtmlTree.DIV(HtmlStyle.block, deprLabel); 132 tdSummary.add(div); 133 } 134 } 135 addSummaryComment(member, firstSentenceTags, tdSummary); 136 } 137 138 /** 139 * Add the summary link for the member. 140 * 141 * @param mw the writer for the member being documented 142 * @param member the member to be documented 143 * @param contentTree the content tree to which the link will be added 144 */ addSummaryLinkComment(AbstractMemberWriter mw, Element member, Content contentTree)145 public void addSummaryLinkComment(AbstractMemberWriter mw, Element member, Content contentTree) { 146 List<? extends DocTree> tags = utils.getFirstSentenceTrees(member); 147 addSummaryLinkComment(mw, member, tags, contentTree); 148 } 149 150 /** 151 * Add the summary link comment. 152 * 153 * @param mw the writer for the member being documented 154 * @param member the member being documented 155 * @param firstSentenceTags the first sentence tags for the member to be documented 156 * @param tdSummary the content tree to which the comment will be added 157 */ addSummaryLinkComment(AbstractMemberWriter mw, Element member, List<? extends DocTree> firstSentenceTags, Content tdSummary)158 public void addSummaryLinkComment(AbstractMemberWriter mw, 159 Element member, List<? extends DocTree> firstSentenceTags, Content tdSummary) { 160 addIndexComment(member, firstSentenceTags, tdSummary); 161 } 162 163 /** 164 * Add the inherited member summary. 165 * 166 * @param mw the writer for the member being documented 167 * @param typeElement the class being documented 168 * @param member the member being documented 169 * @param isFirst true if its the first link being documented 170 * @param linksTree the content tree to which the summary will be added 171 */ addInheritedMemberSummary(AbstractMemberWriter mw, TypeElement typeElement, Element member, boolean isFirst, Content linksTree)172 public void addInheritedMemberSummary(AbstractMemberWriter mw, TypeElement typeElement, 173 Element member, boolean isFirst, Content linksTree) { 174 if (! isFirst) { 175 linksTree.add(", "); 176 } 177 mw.addInheritedSummaryLink(typeElement, member, linksTree); 178 } 179 180 /** 181 * Get the document content header tree 182 * 183 * @return a content tree the document content header 184 */ getContentHeader()185 public Content getContentHeader() { 186 HtmlTree div = new HtmlTree(HtmlTag.DIV); 187 div.setStyle(HtmlStyle.contentContainer); 188 return div; 189 } 190 191 /** 192 * Add the class content tree. 193 * 194 * @param contentTree content tree to which the class content will be added 195 * @param classContentTree class content tree which will be added to the content tree 196 */ addClassContentTree(Content contentTree, Content classContentTree)197 public void addClassContentTree(Content contentTree, Content classContentTree) { 198 mainTree.add(classContentTree); 199 contentTree.add(mainTree); 200 } 201 202 /** 203 * Add the annotation content tree. 204 * 205 * @param contentTree content tree to which the annotation content will be added 206 * @param annotationContentTree annotation content tree which will be added to the content tree 207 */ addAnnotationContentTree(Content contentTree, Content annotationContentTree)208 public void addAnnotationContentTree(Content contentTree, Content annotationContentTree) { 209 addClassContentTree(contentTree, annotationContentTree); 210 } 211 212 /** 213 * Get the member header tree 214 * 215 * @return a content tree for the member header 216 */ getMemberTreeHeader()217 public Content getMemberTreeHeader() { 218 HtmlTree ul = new HtmlTree(HtmlTag.UL); 219 ul.setStyle(HtmlStyle.blockList); 220 return ul; 221 } 222 getMemberInheritedTree()223 public Content getMemberInheritedTree() { 224 HtmlTree div = new HtmlTree(HtmlTag.DIV); 225 div.setStyle(HtmlStyle.inheritedList); 226 return div; 227 } 228 229 /** 230 * Adds the member tree with css style. 231 * @param style the css style to be applied to member tree 232 * @param memberSummaryTree the content tree representing the member summary 233 * @param memberTree the content tree representing the member 234 */ addMemberTree(HtmlStyle style, Content memberSummaryTree, Content memberTree)235 public void addMemberTree(HtmlStyle style, Content memberSummaryTree, Content memberTree) { 236 HtmlTree htmlTree = HtmlTree.SECTION(style, memberTree); 237 memberSummaryTree.add(getMemberTree(htmlTree)); 238 } 239 240 /** 241 * Get the member tree 242 * 243 * @param contentTree the tree used to generate the complete member tree 244 * @return a content tree for the member 245 */ getMemberTree(Content contentTree)246 public Content getMemberTree(Content contentTree) { 247 return HtmlTree.LI(HtmlStyle.blockList, contentTree); 248 } 249 250 /** 251 * Get the member summary tree 252 * 253 * @param contentTree the tree used to generate the member summary tree 254 * @return a content tree for the member summary 255 */ getMemberSummaryTree(Content contentTree)256 public Content getMemberSummaryTree(Content contentTree) { 257 return HtmlTree.SECTION(HtmlStyle.summary, contentTree); 258 } 259 260 /** 261 * Get the member details tree 262 * 263 * @param contentTree the tree used to generate the member details tree 264 * @return a content tree for the member details 265 */ getMemberDetailsTree(Content contentTree)266 public Content getMemberDetailsTree(Content contentTree) { 267 return HtmlTree.SECTION(HtmlStyle.details, contentTree); 268 } 269 270 /** 271 * Get the member tree 272 * 273 * @param style the style class to be added to the content tree 274 * @param contentTree the tree used to generate the complete member tree 275 * @return the member tree 276 */ getMemberTree(HtmlStyle style, Content contentTree)277 public Content getMemberTree(HtmlStyle style, Content contentTree) { 278 return HtmlTree.SECTION(style, contentTree); 279 } 280 } 281