jdk.javadoc.doclet.DocletEnvironment Java Examples

public static boolean run(DocletEnvironment root) {
    ClassDoc operation = root.classes()[0];
    boolean ok =
        checkComment(operation.commentText(), "Arithmetic operations.");

    for (FieldDoc f : operation.fields()) {
        if (f.name().equals("plus")) {
            ok = checkComment(f.commentText(), "Addition") && ok;
            for (MethodDoc m : operation.methods()) {
                if (m.name().equals("eval")) {
                    ok = checkComment(m.commentText(),
                                      "Perform arithmetic operation " +
                                      "represented by this constant.") &&
                        ok;
                    break;
                }
            }
            break;
        }
    }
    if (!ok) {
        throw new Error("Comments don't match expectations.");
    } else {
        return true;
    }
}
 

public static boolean run(DocletEnvironment root) {
    try {
        for (ClassDoc cd : root.classes()) {
            tester.printClass(cd);

            for (SeeTag tag : cd.seeTags()) {
                if (tag.referencedMember() != cd.methods()[0]) {
                    throw new Error("5006659: @see tag meets varArgs");
                }
            }
        }

        return true;
    } catch (IOException e) {
        return false;
    }
}
 

protected void initConfiguration(DocletEnvironment docEnv) {
    if (initialized) {
        throw new IllegalStateException("configuration previously initialized");
    }
    initialized = true;
    this.docEnv = docEnv;
    overviewElement = new OverviewElement(docEnv);
    Splitter specifiedSplitter = new Splitter(docEnv, false);
    specifiedModuleElements = Collections.unmodifiableSet(specifiedSplitter.mset);
    specifiedPackageElements = Collections.unmodifiableSet(specifiedSplitter.pset);
    specifiedTypeElements = Collections.unmodifiableSet(specifiedSplitter.tset);

    Splitter includedSplitter = new Splitter(docEnv, true);
    includedModuleElements = Collections.unmodifiableSet(includedSplitter.mset);
    includedPackageElements = Collections.unmodifiableSet(includedSplitter.pset);
    includedTypeElements = Collections.unmodifiableSet(includedSplitter.tset);
}
 

public static MethodDocumentation fromMethodDoc(DocletEnvironment docEnv,
        Element methodElement) {
    MethodDocumentation md = new MethodDocumentation();
    md.comment = cleanupDocComment(docEnv.getElementUtils().getDocComment(methodElement));

    Optional.ofNullable(docEnv.getDocTrees().getDocCommentTree(methodElement))
            .ifPresent(docCommentTree -> docCommentTree.getBlockTags().forEach(tag -> {
                if (tag.getKind().equals(DocTree.Kind.PARAM)) {
                    ParamTree paramTag = (ParamTree) tag;
                    md.parameters.put(paramTag.getName().toString(),
                            unescapeJava(paramTag.getDescription().toString()));
                } else if (tag instanceof BlockTagTree) {
                    md.tags.put(
                            cleanupTagName(((BlockTagTree) tag).getTagName()),
                            unescapeJava(cleanupTagValue(tag.toString())));
                }
            }));

    return md;
}
 

Set<Element> getAllSelectedElements(DocletEnvironment docenv) {
    Set<Element> result = new TreeSet<Element>((Element e1, Element e2) -> {
        // some grouping by kind preferred
        int rc = e1.getKind().compareTo(e2.getKind());
        if (rc != 0) return rc;
        rc = e1.toString().compareTo(e2.toString());
        if (rc != 0) return rc;
        return Integer.compare(e1.hashCode(), e2.hashCode());
    });
    Set<? extends Element> elements = docenv.getIncludedElements();
    for (ModuleElement me : ElementFilter.modulesIn(elements)) {
        addEnclosedElements(docenv, result, me);
    }
    for (PackageElement pe : ElementFilter.packagesIn(elements)) {
        ModuleElement mdle = docenv.getElementUtils().getModuleOf(pe);
        if (mdle != null)
            addEnclosedElements(docenv, result, mdle);
        addEnclosedElements(docenv, result, pe);
    }
    for (TypeElement te : ElementFilter.typesIn(elements)) {
        addEnclosedElements(docenv, result, te);
    }
    return result;
}
 

/**
 * Start the generation of files. Call generate methods in the individual
 * writers, which will in turn generate the documentation files. Call the
 * TreeWriter generation first to ensure the Class Hierarchy is built
 * first and then can be used in the later generation.
 *
 * @see jdk.doclet.DocletEnvironment
 * @throws DocletException if there is a problem while generating the documentation
 */
private void startGeneration(DocletEnvironment docEnv) throws DocletException {
    if (configuration.getIncludedTypeElements().isEmpty()) {
        messages.error("doclet.No_Public_Classes_To_Document");
        return;
    }
    if (!configuration.setOptions()) {
        return;
    }
    messages.notice("doclet.build_version",
        configuration.getDocletSpecificBuildDate());
    ClassTree classtree = new ClassTree(configuration, configuration.nodeprecated);

    generateClassFiles(docEnv, classtree);

    PackageListWriter.generate(configuration);
    generatePackageFiles(classtree);
    generateModuleFiles();

    generateOtherFiles(docEnv, classtree);
    configuration.tagletManager.printReport();
}
 

public static ClassDocumentation fromClassDoc(DocletEnvironment docEnv,
        Element element) {
    ClassDocumentation cd = new ClassDocumentation();
    cd.setComment(cleanupDocComment(docEnv.getElementUtils().getDocComment(element)));

    element.getEnclosedElements().forEach(fieldOrMethod -> {
        if (fieldOrMethod.getKind().equals(ElementKind.FIELD)) {
            cd.addField(docEnv, fieldOrMethod);
        } else if (fieldOrMethod.getKind().equals(ElementKind.METHOD)
                || fieldOrMethod.getKind().equals(ElementKind.CONSTRUCTOR)) {
            cd.addMethod(docEnv, fieldOrMethod);
        }
    });

    return cd;
}
 

/**
 * Decide the page which will appear first in the right-hand frame. It will
 * be "overview-summary.html" if "-overview" option is used or no
 * "-overview" but the number of packages is more than one. It will be
 * "package-summary.html" of the respective package if there is only one
 * package to document. It will be a class page(first in the sorted order),
 * if only classes are provided on the command line.
 *
 * @param docEnv the doclet environment
 */
protected void setTopFile(DocletEnvironment docEnv) {
    if (!checkForDeprecation(docEnv)) {
        return;
    }
    if (createoverview) {
        topFile = DocPaths.overviewSummary(frames);
    } else {
        if (showModules) {
            topFile = DocPath.empty.resolve(DocPaths.moduleSummary(modules.first()));
        } else if (packages.size() == 1 && packages.first().isUnnamed()) {
            List<TypeElement> classes = new ArrayList<>(getIncludedTypeElements());
            if (!classes.isEmpty()) {
                TypeElement te = getValidClass(classes);
                topFile = DocPath.forClass(utils, te);
            }
        } else if (!packages.isEmpty()) {
            topFile = DocPath.forPackage(packages.first()).resolve(DocPaths.PACKAGE_SUMMARY);
        }
    }
}
 

public boolean run(DocletEnvironment root) {
    DocTrees docTrees = root.getDocTrees();
    System.out.println("classes:" + ElementFilter.typesIn(root.getIncludedElements()));

    Element klass = ElementFilter.typesIn(root.getIncludedElements()).iterator().next();
    String text = "";
    try {
        DocCommentTree dcTree = docTrees.getDocCommentTree(klass, overviewpath);
        text = dcTree.getFullBody().toString();
    } catch (IOException ioe) {
        throw new Error(ioe);
    }

    if (text.length() < 64)
        System.err.println("text: '" + text + "'");
    else
        System.err.println("text: '"
                + text.substring(0, 20)
                + "..."
                + text.substring(text.length() - 20)
                + "'");
    return text.startsWith("ABC") && text.endsWith("XYZ");
}
 

@Override
public boolean run(DocletEnvironment docEnv) {
    Path destinationDir = getDestinationDir();
    ObjectMapper mapper = createObjectMapper();

    docEnv.getIncludedElements()
            .stream()
            .filter(e -> e.getKind().isClass() || e.getKind().isInterface())
            .forEach(classOrInterface -> writeToFile(
                    destinationDir,
                    mapper,
                    findPackageElement(classOrInterface),
                    (TypeElement) classOrInterface,
                    ClassDocumentation.fromClassDoc(docEnv, classOrInterface)
            ));

    return true;
}
 

public boolean run(DocletEnvironment root) {
        DocTrees trees = root.getDocTrees();
        TypeElement cd = ElementFilter.typesIn(root.getIncludedElements()).iterator().next();
        DocCommentTree docCommentTree = trees.getDocCommentTree(cd);
        List<? extends DocTree> tags = docCommentTree.getBody();

        for (int i = 0; i < tags.size(); i++) {
            System.out.println(tags.get(0).getKind());
//            if (!tags[i].name().equals(expectedTags[i]) ||
//                        !tags[i].text().equals(expectedText[i])) {
//                throw new Error("Tag \"" + tags[i] + "\" not as expected");
//            }
        }

        return true;
    }
 

public boolean run(DocletEnvironment root) {
    DocTrees trees = root.getDocTrees();

    SourcePositions sourcePositions = trees.getSourcePositions();
    for (TypeElement klass : ElementFilter.typesIn(root.getIncludedElements())) {
        for (ExecutableElement method : getMethods(klass)) {
            if (method.getSimpleName().toString().equals("tabbedMethod")) {
                TreePath path = trees.getPath(method);
                CompilationUnitTree cu = path.getCompilationUnit();
                long pos = sourcePositions.getStartPosition(cu, path.getLeaf());
                LineMap lineMap = cu.getLineMap();
                long columnNumber = lineMap.getColumnNumber(pos);
                if (columnNumber == 9) {
                    System.out.println(columnNumber + ": OK!");
                    return true;
                } else {
                    System.err.println(columnNumber + ": wrong tab expansion");
                    return false;
                }
            }
        }
    }
    return false;
}
 

public boolean run(DocletEnvironment root) {
    ClassDoc fishdoc = root.classNamed("LangVers.Fish");
    System.out.println(fishdoc);
    if (fishdoc.isEnum()) {
        throw new Error("Enums are not hidden.");
    }

    for (MethodDoc meth : fishdoc.methods()) {
        System.out.println(meth);
        if (meth.flatSignature().indexOf('<') >= 0) {
            throw new Error("Type parameters are not hidden.");
        }
    }

    return true;
}
 

public boolean run(DocletEnvironment root) {
    TypeElement cd = ElementFilter.typesIn(root.getIncludedElements()).iterator().next();
    VariableElement fd = getFields(cd).get(0);
    DocTrees docTrees = root.getDocTrees();
    DocCommentTree docCommentTree = docTrees.getDocCommentTree(fd);
    List<? extends DocTree> firstSentence = docCommentTree.getFirstSentence();
    return true;
}
 

public boolean run(DocletEnvironment root) {
    Set<TypeElement> classes = ElementFilter.typesIn(root.getIncludedElements());
    if (classes.size() != 2)
        throw new Error("1 " + Arrays.asList(classes));
    for (TypeElement clazz : classes) {
        if (getFields(clazz).size() != 1)
            throw new Error("2 " + clazz + " " + getFields(clazz));
    }
    return true;
}
 

protected void generatePackageListFile(DocletEnvironment docEnv) throws DocFileIOException {
    try (BufferedWriter out = new BufferedWriter(file.openWriter())) {
        for (PackageElement pkg : configuration.packages) {
            // if the -nodeprecated option is set and the package is marked as
            // deprecated, do not include it in the packages list.
            if (!(configuration.nodeprecated && utils.isDeprecated(pkg))) {
                out.write(pkg.toString());
                out.newLine();
            }
        }
    } catch (IOException e) {
        throw new DocFileIOException(file, DocFileIOException.Mode.WRITE, e);
    }
}
 

void addEnclosedElements(DocletEnvironment docenv, Set<Element> result, Element e) {
    List<Element> elems = e.getEnclosedElements().stream()
            .filter(el -> docenv.isIncluded(el))
            .collect(Collectors.toList());
    result.addAll(elems);
    for (TypeElement t : ElementFilter.typesIn(elems)) {
        addEnclosedElements(docenv, result, t);
    }
}
 

public boolean run(DocletEnvironment root) {
    Set<TypeElement> classes = ElementFilter.typesIn(root.getIncludedElements());
    if (classes.size() != 1)
        throw new Error("1 " + Arrays.asList(classes));
    TypeElement self = classes.iterator().next();
    DocTrees trees = root.getDocTrees();
    DocCommentTree docCommentTree = trees.getDocCommentTree(self);
    String c = docCommentTree.getFullBody().toString();
    System.out.println("\"" + c + "\"");
    return c.equals("First sentence.\n0\n 1\n  2\n   3\n    4\n     5");
}
 

@Override
public boolean run(DocletEnvironment docenv) {
    this.docEnv = docenv;
    ps.println("ModuleMode" + FS + docenv.getModuleMode());
    printDataSet("Specified", docenv.getSpecifiedElements());
    printDataSet("Included", docenv.getIncludedElements());
    printDataSet("Selected", getAllSelectedElements(docenv));
    System.out.println(sw);
    return true;
}
 

@Override
public boolean run(DocletEnvironment root) {
    Set<TypeElement> classes = ElementFilter.typesIn(root.getIncludedElements());
    if (classes.size() != 1)
        throw new Error("wrong set of classes documented: " +
                Arrays.asList(classes));
    return true;
}
 

/**
 * Constructor. Build the Tree using the Root of this Javadoc run.
 *
 * @param docEnv the DocletEnvironment.
 * @param configuration The current configuration of the doclet.
 */
public ClassTree(DocletEnvironment docEnv, Configuration configuration) {
    this.configuration = configuration;
    this.utils = configuration.utils;
    comparator = utils.makeClassUseComparator();
    baseAnnotationTypes = new TreeSet<>(comparator);
    baseEnums = new TreeSet<>(comparator);
    baseClasses = new TreeSet<>(comparator);
    baseInterfaces = new TreeSet<>(comparator);
    buildTree(configuration.getIncludedTypeElements());
}
 

/**
 * Iterate through all classes and construct documentation for them.
 *
 * @param docEnv      the DocletEnvironment
 * @param classtree the data structure representing the class tree
 * @throws DocletException if there is a problem while generating the documentation
 */
protected void generateClassFiles(DocletEnvironment docEnv, ClassTree classtree)
        throws DocletException {
    generateClassFiles(classtree);
    SortedSet<PackageElement> packages = new TreeSet<>(utils.makePackageComparator());
    packages.addAll(configuration.getSpecifiedPackageElements());
    configuration.modulePackages.values().stream().forEach(packages::addAll);
    for (PackageElement pkg : packages) {
        generateClassFiles(utils.getAllClasses(pkg), classtree);
    }
}
 

/**
 * Generate additional documentation that is added to the API documentation.
 *
 * @param docEnv     the DocletEnvironment
 * @param classtree the data structure representing the class tree
 * @throws DocletException if there is a problem while generating the documentation
 */
protected void generateOtherFiles(DocletEnvironment docEnv, ClassTree classtree)
        throws DocletException {
    BuilderFactory builderFactory = configuration.getBuilderFactory();
    AbstractBuilder constantsSummaryBuilder = builderFactory.getConstantsSummaryBuilder();
    constantsSummaryBuilder.build();
    AbstractBuilder serializedFormBuilder = builderFactory.getSerializedFormBuilder();
    serializedFormBuilder.build();
}
 

@Override
public boolean run(DocletEnvironment docEnv) {
  HashMap<String, ClassInspect> inspects = new HashMap<>();
  DocTrees docTrees = docEnv.getDocTrees();
  for (TypeElement t : ElementFilter.typesIn(docEnv.getIncludedElements())) {
    DocCommentTree docCommentTree = docTrees.getDocCommentTree(t);
    String comment = (docCommentTree != null) ? docCommentTree.getFullBody().toString() : "";
    ClassInspect classInspect = new ClassInspect(t.getSimpleName().toString(), t.getQualifiedName().toString(), comment);
    inspects.put(classInspect.getFullName(), classInspect);
    List<MethodInspect> constructors = new ArrayList<>();
    List<MethodInspect> methods = new ArrayList<>();
    for (Element ee : t.getEnclosedElements()) {
      if (ee.getModifiers().contains(Modifier.PUBLIC) || ee.getModifiers().contains(Modifier.PROTECTED)) {
        if (ee.getKind().equals(ElementKind.CONSTRUCTOR)) {
          constructors.add(getInspect(ee, docTrees));
        } else if (ee.getKind().equals(ElementKind.METHOD)) {
          methods.add(getInspect(ee, docTrees));
        }
      }
    }
    classInspect.setMethods(methods);
    classInspect.setConstructors(constructors);
  }
  SerializeInspect serializeInspect = new SerializeInspect();
  String json = serializeInspect.toJson(inspects);
  serializeInspect.saveToFile(json);
  return true;
}
 

private SourceToHTMLConverter(ConfigurationImpl configuration, DocletEnvironment rd,
        DocPath outputdir) {
    this.configuration  = configuration;
    this.messages = configuration.getMessages();
    this.utils = configuration.utils;
    this.docEnv = rd;
    this.outputdir = outputdir;
}
 

protected boolean checkForDeprecation(DocletEnvironment docEnv) {
    for (TypeElement te : getIncludedTypeElements()) {
        if (isGeneratedDoc(te)) {
            return true;
        }
    }
    return false;
}
 

/**
 * Returns the module documentation level mode.
 * @return the module documentation level mode
 */
public ModuleMode getModuleMode() {
    switch(accessFilter.getAccessValue(ElementKind.MODULE)) {
        case PACKAGE: case PRIVATE:
            return DocletEnvironment.ModuleMode.ALL;
        default:
            return DocletEnvironment.ModuleMode.API;
    }
}
 

public static FieldDocumentation fromFieldDoc(DocletEnvironment docEnv,
        Element fieldElement) {
    FieldDocumentation fd = new FieldDocumentation();
    fd.comment = cleanupDocComment(docEnv.getElementUtils().getDocComment(fieldElement));

    Optional.ofNullable(docEnv.getDocTrees().getDocCommentTree(fieldElement))
            .ifPresent(docCommentTree -> docCommentTree.getBlockTags()
                    .forEach(tag -> fd.addTag(tag)));

    return fd;
}
 

public boolean run(DocletEnvironment root) {
    Set<TypeElement> classes = ElementFilter.typesIn(root.getIncludedElements());
    if (classes.size() != 1)
        throw new Error("1 " + Arrays.asList(classes));
    return true;
}
 

@Override
public abstract boolean run(DocletEnvironment docEnv);