1 /* 2 * Copyright (c) 2003, 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 jdk.javadoc.internal.doclets.formats.html; 27 28 import jdk.javadoc.internal.doclets.formats.html.markup.Table; 29 30 import javax.lang.model.element.Element; 31 import javax.lang.model.element.ExecutableElement; 32 import javax.lang.model.element.TypeElement; 33 import javax.lang.model.type.TypeMirror; 34 35 import jdk.javadoc.internal.doclets.formats.html.markup.TableHeader; 36 import jdk.javadoc.internal.doclets.formats.html.markup.HtmlConstants; 37 import jdk.javadoc.internal.doclets.formats.html.markup.HtmlStyle; 38 import jdk.javadoc.internal.doclets.formats.html.markup.HtmlTag; 39 import jdk.javadoc.internal.doclets.formats.html.markup.HtmlTree; 40 import jdk.javadoc.internal.doclets.formats.html.markup.Navigation; 41 import jdk.javadoc.internal.doclets.formats.html.markup.StringContent; 42 import jdk.javadoc.internal.doclets.toolkit.AnnotationTypeRequiredMemberWriter; 43 import jdk.javadoc.internal.doclets.toolkit.Content; 44 import jdk.javadoc.internal.doclets.toolkit.MemberSummaryWriter; 45 46 47 /** 48 * Writes annotation type required member documentation in HTML format. 49 * 50 * <p><b>This is NOT part of any supported API. 51 * If you write code that depends on this, you do so at your own risk. 52 * This code and its internal interfaces are subject to change or 53 * deletion without notice.</b> 54 * 55 * @author Jamie Ho 56 * @author Bhavesh Patel (Modified) 57 */ 58 public class AnnotationTypeRequiredMemberWriterImpl extends AbstractMemberWriter 59 implements AnnotationTypeRequiredMemberWriter, MemberSummaryWriter { 60 61 /** 62 * Construct a new AnnotationTypeRequiredMemberWriterImpl. 63 * 64 * @param writer the writer that will write the output. 65 * @param annotationType the AnnotationType that holds this member. 66 */ AnnotationTypeRequiredMemberWriterImpl(SubWriterHolderWriter writer, TypeElement annotationType)67 public AnnotationTypeRequiredMemberWriterImpl(SubWriterHolderWriter writer, 68 TypeElement annotationType) { 69 super(writer, annotationType); 70 } 71 72 /** 73 * {@inheritDoc} 74 */ getMemberSummaryHeader(TypeElement typeElement, Content memberSummaryTree)75 public Content getMemberSummaryHeader(TypeElement typeElement, 76 Content memberSummaryTree) { 77 memberSummaryTree.addContent( 78 HtmlConstants.START_OF_ANNOTATION_TYPE_REQUIRED_MEMBER_SUMMARY); 79 Content memberTree = writer.getMemberTreeHeader(); 80 writer.addSummaryHeader(this, typeElement, memberTree); 81 return memberTree; 82 } 83 84 /** 85 * {@inheritDoc} 86 */ getMemberTreeHeader()87 public Content getMemberTreeHeader() { 88 return writer.getMemberTreeHeader(); 89 } 90 91 /** 92 * {@inheritDoc} 93 */ addMemberTree(Content memberSummaryTree, Content memberTree)94 public void addMemberTree(Content memberSummaryTree, Content memberTree) { 95 writer.addMemberTree(memberSummaryTree, memberTree); 96 } 97 98 /** 99 * {@inheritDoc} 100 */ addAnnotationDetailsMarker(Content memberDetails)101 public void addAnnotationDetailsMarker(Content memberDetails) { 102 memberDetails.addContent(HtmlConstants.START_OF_ANNOTATION_TYPE_DETAILS); 103 } 104 105 /** 106 * {@inheritDoc} 107 */ addAnnotationDetailsTreeHeader(TypeElement te, Content memberDetailsTree)108 public void addAnnotationDetailsTreeHeader(TypeElement te, 109 Content memberDetailsTree) { 110 if (!writer.printedAnnotationHeading) { 111 memberDetailsTree.addContent(links.createAnchor( 112 SectionName.ANNOTATION_TYPE_ELEMENT_DETAIL)); 113 Content heading = HtmlTree.HEADING(HtmlConstants.DETAILS_HEADING, 114 contents.annotationTypeDetailsLabel); 115 memberDetailsTree.addContent(heading); 116 writer.printedAnnotationHeading = true; 117 } 118 } 119 120 /** 121 * {@inheritDoc} 122 */ 123 @Override getAnnotationDocTreeHeader(Element member, Content annotationDetailsTree)124 public Content getAnnotationDocTreeHeader(Element member, Content annotationDetailsTree) { 125 String simpleName = name(member); 126 annotationDetailsTree.addContent(links.createAnchor( 127 simpleName + utils.signature((ExecutableElement) member))); 128 Content annotationDocTree = writer.getMemberTreeHeader(); 129 Content heading = new HtmlTree(HtmlConstants.MEMBER_HEADING); 130 heading.addContent(simpleName); 131 annotationDocTree.addContent(heading); 132 return annotationDocTree; 133 } 134 135 /** 136 * {@inheritDoc} 137 */ getSignature(Element member)138 public Content getSignature(Element member) { 139 Content pre = new HtmlTree(HtmlTag.PRE); 140 writer.addAnnotationInfo(member, pre); 141 addModifiers(member, pre); 142 Content link = 143 writer.getLink(new LinkInfoImpl(configuration, 144 LinkInfoImpl.Kind.MEMBER, getType(member))); 145 pre.addContent(link); 146 pre.addContent(Contents.SPACE); 147 if (configuration.linksource) { 148 Content memberName = new StringContent(name(member)); 149 writer.addSrcLink(member, memberName, pre); 150 } else { 151 addName(name(member), pre); 152 } 153 return pre; 154 } 155 156 /** 157 * {@inheritDoc} 158 */ addDeprecated(Element member, Content annotationDocTree)159 public void addDeprecated(Element member, Content annotationDocTree) { 160 addDeprecatedInfo(member, annotationDocTree); 161 } 162 163 /** 164 * {@inheritDoc} 165 */ addComments(Element member, Content annotationDocTree)166 public void addComments(Element member, Content annotationDocTree) { 167 addComment(member, annotationDocTree); 168 } 169 170 /** 171 * {@inheritDoc} 172 */ addTags(Element member, Content annotationDocTree)173 public void addTags(Element member, Content annotationDocTree) { 174 writer.addTagsInfo(member, annotationDocTree); 175 } 176 177 /** 178 * {@inheritDoc} 179 */ getAnnotationDetails(Content annotationDetailsTree)180 public Content getAnnotationDetails(Content annotationDetailsTree) { 181 if (configuration.allowTag(HtmlTag.SECTION)) { 182 HtmlTree htmlTree = HtmlTree.SECTION(getMemberTree(annotationDetailsTree)); 183 return htmlTree; 184 } 185 return getMemberTree(annotationDetailsTree); 186 } 187 188 /** 189 * {@inheritDoc} 190 */ getAnnotationDoc(Content annotationDocTree, boolean isLastContent)191 public Content getAnnotationDoc(Content annotationDocTree, 192 boolean isLastContent) { 193 return getMemberTree(annotationDocTree, isLastContent); 194 } 195 196 /** 197 * {@inheritDoc} 198 */ addSummaryLabel(Content memberTree)199 public void addSummaryLabel(Content memberTree) { 200 Content label = HtmlTree.HEADING(HtmlConstants.SUMMARY_HEADING, 201 contents.annotateTypeRequiredMemberSummaryLabel); 202 memberTree.addContent(label); 203 } 204 205 /** 206 * Get the summary for the member summary table. 207 * 208 * @return a string for the table summary 209 */ 210 // Overridden by AnnotationTypeOptionalMemberWriterImpl getTableSummary()211 protected String getTableSummary() { 212 return resources.getText("doclet.Member_Table_Summary", 213 resources.getText("doclet.Annotation_Type_Required_Member_Summary"), 214 resources.getText("doclet.annotation_type_required_members")); 215 } 216 217 /** 218 * Get the caption for the summary table. 219 * @return the caption 220 */ 221 // Overridden by AnnotationTypeOptionalMemberWriterImpl getCaption()222 protected Content getCaption() { 223 return contents.getContent("doclet.Annotation_Type_Required_Members"); 224 } 225 226 /** 227 * {@inheritDoc} 228 */ 229 @Override getSummaryTableHeader(Element member)230 public TableHeader getSummaryTableHeader(Element member) { 231 return new TableHeader(contents.modifierAndTypeLabel, 232 contents.annotationTypeRequiredMemberLabel, contents.descriptionLabel); 233 } 234 235 /** 236 * {@inheritDoc} 237 */ 238 @Override createSummaryTable()239 protected Table createSummaryTable() { 240 return new Table(configuration.htmlVersion, HtmlStyle.memberSummary) 241 .setSummary(getTableSummary()) 242 .setCaption(getCaption()) 243 .setHeader(getSummaryTableHeader(typeElement)) 244 .setRowScopeColumn(1) 245 .setColumnStyles(HtmlStyle.colFirst, HtmlStyle.colSecond, HtmlStyle.colLast); 246 } 247 248 /** 249 * {@inheritDoc} 250 */ addSummaryAnchor(TypeElement typeElement, Content memberTree)251 public void addSummaryAnchor(TypeElement typeElement, Content memberTree) { 252 memberTree.addContent(links.createAnchor( 253 SectionName.ANNOTATION_TYPE_REQUIRED_ELEMENT_SUMMARY)); 254 } 255 256 /** 257 * {@inheritDoc} 258 */ addInheritedSummaryAnchor(TypeElement typeElement, Content inheritedTree)259 public void addInheritedSummaryAnchor(TypeElement typeElement, Content inheritedTree) { 260 } 261 262 /** 263 * {@inheritDoc} 264 */ addInheritedSummaryLabel(TypeElement typeElement, Content inheritedTree)265 public void addInheritedSummaryLabel(TypeElement typeElement, Content inheritedTree) { 266 } 267 268 /** 269 * {@inheritDoc} 270 */ addSummaryLink(LinkInfoImpl.Kind context, TypeElement typeElement, Element member, Content tdSummary)271 protected void addSummaryLink(LinkInfoImpl.Kind context, TypeElement typeElement, Element member, 272 Content tdSummary) { 273 Content memberLink = HtmlTree.SPAN(HtmlStyle.memberNameLink, 274 writer.getDocLink(context, member, name(member), false)); 275 Content code = HtmlTree.CODE(memberLink); 276 tdSummary.addContent(code); 277 } 278 279 /** 280 * {@inheritDoc} 281 */ addInheritedSummaryLink(TypeElement typeElement, Element member, Content linksTree)282 protected void addInheritedSummaryLink(TypeElement typeElement, 283 Element member, Content linksTree) { 284 //Not applicable. 285 } 286 287 /** 288 * {@inheritDoc} 289 */ addSummaryType(Element member, Content tdSummaryType)290 protected void addSummaryType(Element member, Content tdSummaryType) { 291 addModifierAndType(member, getType(member), tdSummaryType); 292 } 293 294 /** 295 * {@inheritDoc} 296 */ getDeprecatedLink(Element member)297 protected Content getDeprecatedLink(Element member) { 298 String name = utils.getFullyQualifiedName(member) + "." + member.getSimpleName(); 299 return writer.getDocLink(LinkInfoImpl.Kind.MEMBER, member, name); 300 } 301 getType(Element member)302 private TypeMirror getType(Element member) { 303 return utils.isExecutableElement(member) 304 ? utils.getReturnType((ExecutableElement) member) 305 : member.asType(); 306 } 307 } 308