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.toolkit; 27 28 import javax.lang.model.element.TypeElement; 29 30 import jdk.javadoc.internal.doclets.toolkit.util.DocFileIOException; 31 32 /** 33 * The interface for writing annotation type output. 34 * 35 * <p><b>This is NOT part of any supported API. 36 * If you write code that depends on this, you do so at your own risk. 37 * This code and its internal interfaces are subject to change or 38 * deletion without notice.</b> 39 */ 40 41 public interface AnnotationTypeWriter { 42 43 /** 44 * Get the header of the page. 45 * 46 * @param header the header string to write 47 * @return a content tree for the header documentation 48 */ getHeader(String header)49 public Content getHeader(String header); 50 51 /** 52 * Get the annotation content header. 53 * 54 * @return annotation content header that needs to be added to the documentation 55 */ getAnnotationContentHeader()56 public Content getAnnotationContentHeader(); 57 58 /** 59 * Get the annotation information tree header. 60 * 61 * @return annotation information tree header that needs to be added to the documentation 62 */ getAnnotationInfoTreeHeader()63 public Content getAnnotationInfoTreeHeader(); 64 65 /** 66 * Get the annotation information. 67 * 68 * @param annotationInfoTree content tree containing the annotation information 69 * @return a content tree for the annotation 70 */ getAnnotationInfo(Content annotationInfoTree)71 public Content getAnnotationInfo(Content annotationInfoTree); 72 73 /** 74 * Add the signature of the current annotation type. 75 * 76 * @param modifiers the modifiers for the signature 77 * @param annotationInfoTree the annotation content tree to which the signature will be added 78 */ addAnnotationTypeSignature(String modifiers, Content annotationInfoTree)79 public void addAnnotationTypeSignature(String modifiers, Content annotationInfoTree); 80 81 /** 82 * Build the annotation type description. 83 * 84 * @param annotationInfoTree content tree to which the description will be added 85 */ addAnnotationTypeDescription(Content annotationInfoTree)86 public void addAnnotationTypeDescription(Content annotationInfoTree); 87 88 /** 89 * Add the tag information for the current annotation type. 90 * 91 * @param annotationInfoTree content tree to which the tag information will be added 92 */ addAnnotationTypeTagInfo(Content annotationInfoTree)93 public void addAnnotationTypeTagInfo(Content annotationInfoTree); 94 95 /** 96 * If this annotation is deprecated, add the appropriate information. 97 * 98 * @param annotationInfoTree content tree to which the deprecated information will be added 99 */ addAnnotationTypeDeprecationInfo(Content annotationInfoTree)100 public void addAnnotationTypeDeprecationInfo (Content annotationInfoTree); 101 102 /** 103 * Get the member tree header for the annotation type. 104 * 105 * @return a content tree for the member tree header 106 */ getMemberTreeHeader()107 public Content getMemberTreeHeader(); 108 109 /** 110 * Add the annotation content tree to the documentation content tree. 111 * 112 * @param annotationContentTree annotation content tree which will be added to the content tree 113 */ addAnnotationContentTree(Content annotationContentTree)114 public void addAnnotationContentTree(Content annotationContentTree); 115 116 /** 117 * Get the member tree. 118 * 119 * @param memberTree the content tree that will be modified and returned 120 * @return a content tree for the member 121 */ getMemberTree(Content memberTree)122 public Content getMemberTree(Content memberTree); 123 124 /** 125 * Get the member summary tree. 126 * 127 * @param memberTree the content tree that will be used to build the summary tree 128 * @return a content tree for the member summary 129 */ getMemberSummaryTree(Content memberTree)130 public Content getMemberSummaryTree(Content memberTree); 131 132 /** 133 * Get the member details tree. 134 * 135 * @param memberTree the content tree that will be used to build the details tree 136 * @return a content tree for the member details 137 */ getMemberDetailsTree(Content memberTree)138 public Content getMemberDetailsTree(Content memberTree); 139 140 /** 141 * Add the footer of the page. 142 */ addFooter()143 public void addFooter(); 144 145 /** 146 * Print the document. 147 * 148 * @param contentTree content tree that will be printed as a document 149 * @throws DocFileIOException if there is a problem while writing the document 150 */ printDocument(Content contentTree)151 public void printDocument(Content contentTree) throws DocFileIOException; 152 153 /** 154 * Return the {@link TypeElement} being documented. 155 * 156 * @return the TypeElement representing the annotation being documented. 157 */ getAnnotationTypeElement()158 public TypeElement getAnnotationTypeElement(); 159 } 160