1/* 2 * Copyright (c) 2015, 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.doclet; 27 28import java.util.Set; 29 30import javax.lang.model.SourceVersion; 31import javax.lang.model.element.Element; 32import javax.lang.model.element.TypeElement; 33import javax.lang.model.util.Elements; 34import javax.lang.model.util.Types; 35import javax.tools.JavaFileManager; 36import javax.tools.JavaFileObject.Kind; 37 38import com.sun.source.util.DocTrees; 39 40/** 41 * Represents the operating environment of a single invocation 42 * of the doclet. This object can be used to access the program 43 * structures, various utilities and the user specified elements 44 * on the command line. 45 * 46 * @since 9 47 */ 48public interface DocletEnvironment { 49 50 /** 51 * Returns the elements <a href="package-summary.html#specified">specified</a> 52 * when the tool is invoked. 53 * 54 * @return the set of specified elements 55 */ 56 Set<? extends Element> getSpecifiedElements(); 57 58 /** 59 * Returns the module, package and type elements that should be 60 * <a href="package-summary.html#included">included</a> in the 61 * documentation. 62 * 63 * @return the set of included elements 64 */ 65 Set<? extends Element> getIncludedElements(); 66 67 /** 68 * Returns an instance of the {@code DocTrees} utility class. 69 * This class provides methods to access {@code TreePath}s, {@code DocCommentTree}s 70 * and so on. 71 * 72 * @return a utility class to operate on doc trees 73 */ 74 DocTrees getDocTrees(); 75 76 /** 77 * Returns an instance of the {@code Elements} utility class. 78 * This class provides methods for operating on 79 * {@link javax.lang.model.element.Element elements}. 80 * 81 * @return a utility class to operate on elements 82 */ 83 Elements getElementUtils(); 84 85 /** 86 * Returns an instance of the {@code Types} utility class. 87 * This class provides methods for operating on 88 * {@link javax.lang.model.type.TypeMirror type mirrors}. 89 * 90 * @return a utility class to operate on type mirrors 91 */ 92 Types getTypeUtils(); 93 94 /** 95 * Returns true if an element should be 96 * <a href="package-summary.html#included">included</a> in the 97 * documentation. 98 * 99 * @param e the element 100 * @return true if included, false otherwise 101 */ 102 boolean isIncluded(Element e); 103 104 /** 105 * Returns true if the element is <a href="package-summary.html#selected">selected</a>. 106 * 107 * @param e the element 108 * @return true if selected, false otherwise 109 */ 110 boolean isSelected(Element e); 111 112 /** 113 * Returns the file manager used to read and write files. 114 * 115 * @return the file manager used to read and write files 116 */ 117 JavaFileManager getJavaFileManager(); 118 119 /** 120 * Returns the source version of the source files that were read. 121 * 122 * @return the source version 123 */ 124 SourceVersion getSourceVersion(); 125 126 /** 127 * Returns the required level of module documentation. 128 * 129 * @return the required level of module documentation 130 */ 131 ModuleMode getModuleMode(); 132 133 /** 134 * Returns the file kind of a type element. 135 * 136 * @param type the type element 137 * @return the file kind 138 */ 139 Kind getFileKind(TypeElement type); 140 141 enum ModuleMode { 142 /** Indicate API level documentation is required */ 143 API, 144 /** Indicate Detailed documentation is required */ 145 ALL 146 } 147} 148