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