langtools/src/jdk.javadoc/share/classes/jdk/javadoc/doclet/DocletEnvironment.java
author ksrini
Thu, 18 Aug 2016 05:48:35 -0700
changeset 40508 74ef30d16fb9
parent 35426 374342e56a56
child 42277 2668b0bc7ad7
permissions -rw-r--r--
8159305: Enhance the javadoc tool to support module related options Reviewed-by: bpatel, jjg
Ignore whitespace changes - Everywhere: Within whitespace: At end of lines:
35426
374342e56a56 8035473: [javadoc] Revamp the existing Doclet APIs
ksrini
parents:
diff changeset
     1
/*
374342e56a56 8035473: [javadoc] Revamp the existing Doclet APIs
ksrini
parents:
diff changeset
     2
 * Copyright (c) 2015, 2016, Oracle and/or its affiliates. All rights reserved.
374342e56a56 8035473: [javadoc] Revamp the existing Doclet APIs
ksrini
parents:
diff changeset
     3
 * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
374342e56a56 8035473: [javadoc] Revamp the existing Doclet APIs
ksrini
parents:
diff changeset
     4
 *
374342e56a56 8035473: [javadoc] Revamp the existing Doclet APIs
ksrini
parents:
diff changeset
     5
 * This code is free software; you can redistribute it and/or modify it
374342e56a56 8035473: [javadoc] Revamp the existing Doclet APIs
ksrini
parents:
diff changeset
     6
 * under the terms of the GNU General Public License version 2 only, as
374342e56a56 8035473: [javadoc] Revamp the existing Doclet APIs
ksrini
parents:
diff changeset
     7
 * published by the Free Software Foundation.  Oracle designates this
374342e56a56 8035473: [javadoc] Revamp the existing Doclet APIs
ksrini
parents:
diff changeset
     8
 * particular file as subject to the "Classpath" exception as provided
374342e56a56 8035473: [javadoc] Revamp the existing Doclet APIs
ksrini
parents:
diff changeset
     9
 * by Oracle in the LICENSE file that accompanied this code.
374342e56a56 8035473: [javadoc] Revamp the existing Doclet APIs
ksrini
parents:
diff changeset
    10
 *
374342e56a56 8035473: [javadoc] Revamp the existing Doclet APIs
ksrini
parents:
diff changeset
    11
 * This code is distributed in the hope that it will be useful, but WITHOUT
374342e56a56 8035473: [javadoc] Revamp the existing Doclet APIs
ksrini
parents:
diff changeset
    12
 * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
374342e56a56 8035473: [javadoc] Revamp the existing Doclet APIs
ksrini
parents:
diff changeset
    13
 * FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License
374342e56a56 8035473: [javadoc] Revamp the existing Doclet APIs
ksrini
parents:
diff changeset
    14
 * version 2 for more details (a copy is included in the LICENSE file that
374342e56a56 8035473: [javadoc] Revamp the existing Doclet APIs
ksrini
parents:
diff changeset
    15
 * accompanied this code).
374342e56a56 8035473: [javadoc] Revamp the existing Doclet APIs
ksrini
parents:
diff changeset
    16
 *
374342e56a56 8035473: [javadoc] Revamp the existing Doclet APIs
ksrini
parents:
diff changeset
    17
 * You should have received a copy of the GNU General Public License version
374342e56a56 8035473: [javadoc] Revamp the existing Doclet APIs
ksrini
parents:
diff changeset
    18
 * 2 along with this work; if not, write to the Free Software Foundation,
374342e56a56 8035473: [javadoc] Revamp the existing Doclet APIs
ksrini
parents:
diff changeset
    19
 * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
374342e56a56 8035473: [javadoc] Revamp the existing Doclet APIs
ksrini
parents:
diff changeset
    20
 *
374342e56a56 8035473: [javadoc] Revamp the existing Doclet APIs
ksrini
parents:
diff changeset
    21
 * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
374342e56a56 8035473: [javadoc] Revamp the existing Doclet APIs
ksrini
parents:
diff changeset
    22
 * or visit www.oracle.com if you need additional information or have any
374342e56a56 8035473: [javadoc] Revamp the existing Doclet APIs
ksrini
parents:
diff changeset
    23
 * questions.
374342e56a56 8035473: [javadoc] Revamp the existing Doclet APIs
ksrini
parents:
diff changeset
    24
 */
374342e56a56 8035473: [javadoc] Revamp the existing Doclet APIs
ksrini
parents:
diff changeset
    25
374342e56a56 8035473: [javadoc] Revamp the existing Doclet APIs
ksrini
parents:
diff changeset
    26
package jdk.javadoc.doclet;
374342e56a56 8035473: [javadoc] Revamp the existing Doclet APIs
ksrini
parents:
diff changeset
    27
374342e56a56 8035473: [javadoc] Revamp the existing Doclet APIs
ksrini
parents:
diff changeset
    28
import java.util.List;
374342e56a56 8035473: [javadoc] Revamp the existing Doclet APIs
ksrini
parents:
diff changeset
    29
import java.util.Set;
374342e56a56 8035473: [javadoc] Revamp the existing Doclet APIs
ksrini
parents:
diff changeset
    30
374342e56a56 8035473: [javadoc] Revamp the existing Doclet APIs
ksrini
parents:
diff changeset
    31
import javax.lang.model.SourceVersion;
374342e56a56 8035473: [javadoc] Revamp the existing Doclet APIs
ksrini
parents:
diff changeset
    32
import javax.lang.model.element.Element;
40508
74ef30d16fb9 8159305: Enhance the javadoc tool to support module related options
ksrini
parents: 35426
diff changeset
    33
import javax.lang.model.element.ModuleElement;
74ef30d16fb9 8159305: Enhance the javadoc tool to support module related options
ksrini
parents: 35426
diff changeset
    34
import javax.lang.model.element.PackageElement;
35426
374342e56a56 8035473: [javadoc] Revamp the existing Doclet APIs
ksrini
parents:
diff changeset
    35
import javax.lang.model.element.TypeElement;
374342e56a56 8035473: [javadoc] Revamp the existing Doclet APIs
ksrini
parents:
diff changeset
    36
import javax.lang.model.util.Elements;
374342e56a56 8035473: [javadoc] Revamp the existing Doclet APIs
ksrini
parents:
diff changeset
    37
import javax.lang.model.util.Types;
374342e56a56 8035473: [javadoc] Revamp the existing Doclet APIs
ksrini
parents:
diff changeset
    38
import javax.tools.JavaFileManager;
374342e56a56 8035473: [javadoc] Revamp the existing Doclet APIs
ksrini
parents:
diff changeset
    39
374342e56a56 8035473: [javadoc] Revamp the existing Doclet APIs
ksrini
parents:
diff changeset
    40
import com.sun.source.util.DocTrees;
374342e56a56 8035473: [javadoc] Revamp the existing Doclet APIs
ksrini
parents:
diff changeset
    41
374342e56a56 8035473: [javadoc] Revamp the existing Doclet APIs
ksrini
parents:
diff changeset
    42
/**
374342e56a56 8035473: [javadoc] Revamp the existing Doclet APIs
ksrini
parents:
diff changeset
    43
 * Represents the operating environment of a single invocation
374342e56a56 8035473: [javadoc] Revamp the existing Doclet APIs
ksrini
parents:
diff changeset
    44
 * of the doclet. This object can be used to access the program
374342e56a56 8035473: [javadoc] Revamp the existing Doclet APIs
ksrini
parents:
diff changeset
    45
 * structures, various utilities and the user specified elements
374342e56a56 8035473: [javadoc] Revamp the existing Doclet APIs
ksrini
parents:
diff changeset
    46
 * on the command line.
374342e56a56 8035473: [javadoc] Revamp the existing Doclet APIs
ksrini
parents:
diff changeset
    47
 *
374342e56a56 8035473: [javadoc] Revamp the existing Doclet APIs
ksrini
parents:
diff changeset
    48
 * @since 9
374342e56a56 8035473: [javadoc] Revamp the existing Doclet APIs
ksrini
parents:
diff changeset
    49
 */
374342e56a56 8035473: [javadoc] Revamp the existing Doclet APIs
ksrini
parents:
diff changeset
    50
public interface DocletEnvironment {
374342e56a56 8035473: [javadoc] Revamp the existing Doclet APIs
ksrini
parents:
diff changeset
    51
    /**
374342e56a56 8035473: [javadoc] Revamp the existing Doclet APIs
ksrini
parents:
diff changeset
    52
     * Returns the <a href="package-summary.html#included">included</a>
40508
74ef30d16fb9 8159305: Enhance the javadoc tool to support module related options
ksrini
parents: 35426
diff changeset
    53
     * modules.
74ef30d16fb9 8159305: Enhance the javadoc tool to support module related options
ksrini
parents: 35426
diff changeset
    54
     *
74ef30d16fb9 8159305: Enhance the javadoc tool to support module related options
ksrini
parents: 35426
diff changeset
    55
     * @return a set of included module elements
74ef30d16fb9 8159305: Enhance the javadoc tool to support module related options
ksrini
parents: 35426
diff changeset
    56
     */
74ef30d16fb9 8159305: Enhance the javadoc tool to support module related options
ksrini
parents: 35426
diff changeset
    57
    Set<ModuleElement> getIncludedModuleElements();
74ef30d16fb9 8159305: Enhance the javadoc tool to support module related options
ksrini
parents: 35426
diff changeset
    58
74ef30d16fb9 8159305: Enhance the javadoc tool to support module related options
ksrini
parents: 35426
diff changeset
    59
    /**
74ef30d16fb9 8159305: Enhance the javadoc tool to support module related options
ksrini
parents: 35426
diff changeset
    60
     * Returns the <a href="package-summary.html#included">included</a>
74ef30d16fb9 8159305: Enhance the javadoc tool to support module related options
ksrini
parents: 35426
diff changeset
    61
     * annotation types, classes, interfaces and enums in all packages.
35426
374342e56a56 8035473: [javadoc] Revamp the existing Doclet APIs
ksrini
parents:
diff changeset
    62
     *
40508
74ef30d16fb9 8159305: Enhance the javadoc tool to support module related options
ksrini
parents: 35426
diff changeset
    63
     * @return a set of included type elements
35426
374342e56a56 8035473: [javadoc] Revamp the existing Doclet APIs
ksrini
parents:
diff changeset
    64
     */
40508
74ef30d16fb9 8159305: Enhance the javadoc tool to support module related options
ksrini
parents: 35426
diff changeset
    65
    Set<TypeElement> getIncludedTypeElements();
74ef30d16fb9 8159305: Enhance the javadoc tool to support module related options
ksrini
parents: 35426
diff changeset
    66
74ef30d16fb9 8159305: Enhance the javadoc tool to support module related options
ksrini
parents: 35426
diff changeset
    67
    /**
74ef30d16fb9 8159305: Enhance the javadoc tool to support module related options
ksrini
parents: 35426
diff changeset
    68
     * Returns the <a href="package-summary.html#included">included</a>
74ef30d16fb9 8159305: Enhance the javadoc tool to support module related options
ksrini
parents: 35426
diff changeset
    69
     * packages.
74ef30d16fb9 8159305: Enhance the javadoc tool to support module related options
ksrini
parents: 35426
diff changeset
    70
     *
74ef30d16fb9 8159305: Enhance the javadoc tool to support module related options
ksrini
parents: 35426
diff changeset
    71
     * @return a set of included package elements
74ef30d16fb9 8159305: Enhance the javadoc tool to support module related options
ksrini
parents: 35426
diff changeset
    72
     */
74ef30d16fb9 8159305: Enhance the javadoc tool to support module related options
ksrini
parents: 35426
diff changeset
    73
    Set<PackageElement> getIncludedPackageElements();
35426
374342e56a56 8035473: [javadoc] Revamp the existing Doclet APIs
ksrini
parents:
diff changeset
    74
374342e56a56 8035473: [javadoc] Revamp the existing Doclet APIs
ksrini
parents:
diff changeset
    75
    /**
374342e56a56 8035473: [javadoc] Revamp the existing Doclet APIs
ksrini
parents:
diff changeset
    76
     * Returns an instance of the {@code DocTrees} utility class.
374342e56a56 8035473: [javadoc] Revamp the existing Doclet APIs
ksrini
parents:
diff changeset
    77
     * This class provides methods to access {@code TreePath}s, {@code DocCommentTree}s
374342e56a56 8035473: [javadoc] Revamp the existing Doclet APIs
ksrini
parents:
diff changeset
    78
     * and so on.
40508
74ef30d16fb9 8159305: Enhance the javadoc tool to support module related options
ksrini
parents: 35426
diff changeset
    79
     *
74ef30d16fb9 8159305: Enhance the javadoc tool to support module related options
ksrini
parents: 35426
diff changeset
    80
     * @return a utility class to operate on doc trees
35426
374342e56a56 8035473: [javadoc] Revamp the existing Doclet APIs
ksrini
parents:
diff changeset
    81
     */
374342e56a56 8035473: [javadoc] Revamp the existing Doclet APIs
ksrini
parents:
diff changeset
    82
    DocTrees getDocTrees();
374342e56a56 8035473: [javadoc] Revamp the existing Doclet APIs
ksrini
parents:
diff changeset
    83
374342e56a56 8035473: [javadoc] Revamp the existing Doclet APIs
ksrini
parents:
diff changeset
    84
    /**
374342e56a56 8035473: [javadoc] Revamp the existing Doclet APIs
ksrini
parents:
diff changeset
    85
     * Returns an instance of the {@code Elements} utility class.
374342e56a56 8035473: [javadoc] Revamp the existing Doclet APIs
ksrini
parents:
diff changeset
    86
     * This class provides methods for operating on
374342e56a56 8035473: [javadoc] Revamp the existing Doclet APIs
ksrini
parents:
diff changeset
    87
     * {@link javax.lang.model.element.Element elements}.
40508
74ef30d16fb9 8159305: Enhance the javadoc tool to support module related options
ksrini
parents: 35426
diff changeset
    88
     *
35426
374342e56a56 8035473: [javadoc] Revamp the existing Doclet APIs
ksrini
parents:
diff changeset
    89
     * @return a utility class to operate on elements
374342e56a56 8035473: [javadoc] Revamp the existing Doclet APIs
ksrini
parents:
diff changeset
    90
     */
374342e56a56 8035473: [javadoc] Revamp the existing Doclet APIs
ksrini
parents:
diff changeset
    91
    Elements getElementUtils();
374342e56a56 8035473: [javadoc] Revamp the existing Doclet APIs
ksrini
parents:
diff changeset
    92
374342e56a56 8035473: [javadoc] Revamp the existing Doclet APIs
ksrini
parents:
diff changeset
    93
    /**
40508
74ef30d16fb9 8159305: Enhance the javadoc tool to support module related options
ksrini
parents: 35426
diff changeset
    94
     * Returns the <a href="package-summary.html#included">selected</a>
74ef30d16fb9 8159305: Enhance the javadoc tool to support module related options
ksrini
parents: 35426
diff changeset
    95
     * elements that can be documented.
35426
374342e56a56 8035473: [javadoc] Revamp the existing Doclet APIs
ksrini
parents:
diff changeset
    96
     *
374342e56a56 8035473: [javadoc] Revamp the existing Doclet APIs
ksrini
parents:
diff changeset
    97
     * @param elements those that need to be checked
40508
74ef30d16fb9 8159305: Enhance the javadoc tool to support module related options
ksrini
parents: 35426
diff changeset
    98
     * @return elements selected, an empty list if none
35426
374342e56a56 8035473: [javadoc] Revamp the existing Doclet APIs
ksrini
parents:
diff changeset
    99
     */
374342e56a56 8035473: [javadoc] Revamp the existing Doclet APIs
ksrini
parents:
diff changeset
   100
    List<Element> getSelectedElements(List<? extends Element> elements);
374342e56a56 8035473: [javadoc] Revamp the existing Doclet APIs
ksrini
parents:
diff changeset
   101
374342e56a56 8035473: [javadoc] Revamp the existing Doclet APIs
ksrini
parents:
diff changeset
   102
    /**
40508
74ef30d16fb9 8159305: Enhance the javadoc tool to support module related options
ksrini
parents: 35426
diff changeset
   103
     * Returns the elements <a href="package-summary.html#specified">specified</a>
74ef30d16fb9 8159305: Enhance the javadoc tool to support module related options
ksrini
parents: 35426
diff changeset
   104
     * on the command line, usually module elements, package elements and type elements.
35426
374342e56a56 8035473: [javadoc] Revamp the existing Doclet APIs
ksrini
parents:
diff changeset
   105
     * If {@code -subpackages} and {@code -exclude} options
374342e56a56 8035473: [javadoc] Revamp the existing Doclet APIs
ksrini
parents:
diff changeset
   106
     * are used, return all the non-excluded packages.
374342e56a56 8035473: [javadoc] Revamp the existing Doclet APIs
ksrini
parents:
diff changeset
   107
     *
374342e56a56 8035473: [javadoc] Revamp the existing Doclet APIs
ksrini
parents:
diff changeset
   108
     * @return elements specified on the command line.
374342e56a56 8035473: [javadoc] Revamp the existing Doclet APIs
ksrini
parents:
diff changeset
   109
     */
374342e56a56 8035473: [javadoc] Revamp the existing Doclet APIs
ksrini
parents:
diff changeset
   110
    Set<Element> getSpecifiedElements();
374342e56a56 8035473: [javadoc] Revamp the existing Doclet APIs
ksrini
parents:
diff changeset
   111
374342e56a56 8035473: [javadoc] Revamp the existing Doclet APIs
ksrini
parents:
diff changeset
   112
    /**
374342e56a56 8035473: [javadoc] Revamp the existing Doclet APIs
ksrini
parents:
diff changeset
   113
     * Returns an instance of the {@code Types} utility class.
374342e56a56 8035473: [javadoc] Revamp the existing Doclet APIs
ksrini
parents:
diff changeset
   114
     * This class provides methods for operating on
374342e56a56 8035473: [javadoc] Revamp the existing Doclet APIs
ksrini
parents:
diff changeset
   115
     * {@link javax.lang.model.type.TypeMirror type mirrors}.
40508
74ef30d16fb9 8159305: Enhance the javadoc tool to support module related options
ksrini
parents: 35426
diff changeset
   116
     *
35426
374342e56a56 8035473: [javadoc] Revamp the existing Doclet APIs
ksrini
parents:
diff changeset
   117
     * @return a utility class to operate on type mirrors
374342e56a56 8035473: [javadoc] Revamp the existing Doclet APIs
ksrini
parents:
diff changeset
   118
     */
374342e56a56 8035473: [javadoc] Revamp the existing Doclet APIs
ksrini
parents:
diff changeset
   119
    Types getTypeUtils();
374342e56a56 8035473: [javadoc] Revamp the existing Doclet APIs
ksrini
parents:
diff changeset
   120
374342e56a56 8035473: [javadoc] Revamp the existing Doclet APIs
ksrini
parents:
diff changeset
   121
    /**
374342e56a56 8035473: [javadoc] Revamp the existing Doclet APIs
ksrini
parents:
diff changeset
   122
     * Indicates if an element is <a href="package-summary.html#included">included</a>.
374342e56a56 8035473: [javadoc] Revamp the existing Doclet APIs
ksrini
parents:
diff changeset
   123
     *
374342e56a56 8035473: [javadoc] Revamp the existing Doclet APIs
ksrini
parents:
diff changeset
   124
     * @param e the Element in question
374342e56a56 8035473: [javadoc] Revamp the existing Doclet APIs
ksrini
parents:
diff changeset
   125
     * @return true if included, false otherwise
374342e56a56 8035473: [javadoc] Revamp the existing Doclet APIs
ksrini
parents:
diff changeset
   126
     */
374342e56a56 8035473: [javadoc] Revamp the existing Doclet APIs
ksrini
parents:
diff changeset
   127
    boolean isIncluded(Element e);
374342e56a56 8035473: [javadoc] Revamp the existing Doclet APIs
ksrini
parents:
diff changeset
   128
374342e56a56 8035473: [javadoc] Revamp the existing Doclet APIs
ksrini
parents:
diff changeset
   129
    /**
374342e56a56 8035473: [javadoc] Revamp the existing Doclet APIs
ksrini
parents:
diff changeset
   130
     * Returns the file manager used to read and write files.
374342e56a56 8035473: [javadoc] Revamp the existing Doclet APIs
ksrini
parents:
diff changeset
   131
     *
374342e56a56 8035473: [javadoc] Revamp the existing Doclet APIs
ksrini
parents:
diff changeset
   132
     * @return the file manager used to read and write files
374342e56a56 8035473: [javadoc] Revamp the existing Doclet APIs
ksrini
parents:
diff changeset
   133
     */
374342e56a56 8035473: [javadoc] Revamp the existing Doclet APIs
ksrini
parents:
diff changeset
   134
    JavaFileManager getJavaFileManager();
374342e56a56 8035473: [javadoc] Revamp the existing Doclet APIs
ksrini
parents:
diff changeset
   135
374342e56a56 8035473: [javadoc] Revamp the existing Doclet APIs
ksrini
parents:
diff changeset
   136
    /**
374342e56a56 8035473: [javadoc] Revamp the existing Doclet APIs
ksrini
parents:
diff changeset
   137
     * Returns the source version of the source files that were read.
374342e56a56 8035473: [javadoc] Revamp the existing Doclet APIs
ksrini
parents:
diff changeset
   138
     *
374342e56a56 8035473: [javadoc] Revamp the existing Doclet APIs
ksrini
parents:
diff changeset
   139
     * @return the source version
374342e56a56 8035473: [javadoc] Revamp the existing Doclet APIs
ksrini
parents:
diff changeset
   140
     */
374342e56a56 8035473: [javadoc] Revamp the existing Doclet APIs
ksrini
parents:
diff changeset
   141
    SourceVersion getSourceVersion();
40508
74ef30d16fb9 8159305: Enhance the javadoc tool to support module related options
ksrini
parents: 35426
diff changeset
   142
74ef30d16fb9 8159305: Enhance the javadoc tool to support module related options
ksrini
parents: 35426
diff changeset
   143
    /**
74ef30d16fb9 8159305: Enhance the javadoc tool to support module related options
ksrini
parents: 35426
diff changeset
   144
     * Returns the required level of module documentation.
74ef30d16fb9 8159305: Enhance the javadoc tool to support module related options
ksrini
parents: 35426
diff changeset
   145
     *
74ef30d16fb9 8159305: Enhance the javadoc tool to support module related options
ksrini
parents: 35426
diff changeset
   146
     * @return the required level of module documentation
74ef30d16fb9 8159305: Enhance the javadoc tool to support module related options
ksrini
parents: 35426
diff changeset
   147
     */
74ef30d16fb9 8159305: Enhance the javadoc tool to support module related options
ksrini
parents: 35426
diff changeset
   148
    public ModuleMode getModuleMode();
74ef30d16fb9 8159305: Enhance the javadoc tool to support module related options
ksrini
parents: 35426
diff changeset
   149
74ef30d16fb9 8159305: Enhance the javadoc tool to support module related options
ksrini
parents: 35426
diff changeset
   150
    enum ModuleMode {
74ef30d16fb9 8159305: Enhance the javadoc tool to support module related options
ksrini
parents: 35426
diff changeset
   151
        /** Indicate API level documentation is required */
74ef30d16fb9 8159305: Enhance the javadoc tool to support module related options
ksrini
parents: 35426
diff changeset
   152
        API,
74ef30d16fb9 8159305: Enhance the javadoc tool to support module related options
ksrini
parents: 35426
diff changeset
   153
        /** Indicate Detailed documentation is required */
74ef30d16fb9 8159305: Enhance the javadoc tool to support module related options
ksrini
parents: 35426
diff changeset
   154
        ALL
74ef30d16fb9 8159305: Enhance the javadoc tool to support module related options
ksrini
parents: 35426
diff changeset
   155
    }
35426
374342e56a56 8035473: [javadoc] Revamp the existing Doclet APIs
ksrini
parents:
diff changeset
   156
}