import com.sun.source.util.DocTreePath; //导入依赖的package包/类
/**
 * Factory method for creating {@link DocTreePathHandle}.
 *
 * @param docTreePath for which the {@link DocTreePathHandle} should be created.
 * @param javac
 * @return a new {@link DocTreePathHandle}
 * @throws java.lang.IllegalArgumentException if arguments are not supported
 */
public static DocTreePathHandle create(final DocTreePath docTreePath, CompilationInfo javac) throws IllegalArgumentException {
    Parameters.notNull("docTreePath", docTreePath);
    Parameters.notNull("javac", javac);

    TreePathHandle treePathHandle = TreePathHandle.create(docTreePath.getTreePath(), javac);
    if(treePathHandle.getFileObject() == null) {
        return null;
    }
    int position = (int) ((DCTree) docTreePath.getLeaf()).getSourcePosition((DCTree.DCDocComment)docTreePath.getDocComment());
    if (position == (-1)) {
        DocTree docTree = docTreePath.getLeaf();
        if(docTree == docTreePath.getDocComment()) {
            return new DocTreePathHandle(new DocCommentDelegate(treePathHandle));
        }
        int index = listChildren(docTreePath.getParentPath().getLeaf()).indexOf(docTree);
        assert index != (-1);
        return new DocTreePathHandle(new CountingDelegate(treePathHandle, index, docTreePath.getLeaf().getKind()));
    }
    Position pos = createPositionRef(treePathHandle.getFileObject(), position, Bias.Forward);
    return new DocTreePathHandle(new DocTreeDelegate(pos, new DocTreeDelegate.KindPath(docTreePath), treePathHandle));
}
 

import com.sun.source.util.DocTreePath; //导入依赖的package包/类
/**
 * Resolves an {@link TreePath} from the {@link TreePathHandle}.
 *
 * @param javac representing the
 * {@link javax.tools.CompilationTask}
 * @return resolved subclass of {@link Element} or null if the element
 * does not exist on the classpath/sourcepath of
 * {@link javax.tools.CompilationTask}.
 * @throws IllegalArgumentException when this {@link TreePathHandle} is
 * not created for a source represented by the compilationInfo.
 */
public DocTreePath resolve(final CompilationInfo javac) throws IllegalArgumentException {
    assert javac != null;
    TreePath treePath = treePathHandle.resolve(javac);
    if(treePath == null) {
        throw new IllegalArgumentException("treePathHandle.resolve(compilationInfo) returned null for treePathHandle " + treePathHandle);    //NOI18N
    }
    DocTreePath tp = null;
    DocCommentTree doc = javac.getDocTrees().getDocCommentTree(treePath);
    if (doc == null) {
        // no doc comment for the TreePath
        return null;
    }
    int pos = position.getOffset();
    tp = resolvePathForPos(javac, treePath, doc, pos + 1);
    if (tp != null) {
        return tp;
    }
    tp = resolvePathForPos(javac, treePath, doc, pos);
    return tp;
}
 

import com.sun.source.util.DocTreePath; //导入依赖的package包/类
private static DocTreePath getChild(@NonNull DocCommentTree t, final int index) {
    final DocTreePath[] result = new DocTreePath[1];

    t.accept(new DocTreePathScanner<DocTreePath, Void>() {
        int count = 0;
        @Override
        public DocTreePath scan(DocTree node, Void p) {
            if(index == count) {
                result[0] = getCurrentPath();
            }
            return null;
        }
    }, null);

    return result[0];
}
 

import com.sun.source.util.DocTreePath; //导入依赖的package包/类
private static Iterable<? extends TreePath> referenceEmbeddedSourceNodes(CompilationInfo info, DocTreePath ref) {
    List<TreePath> result = new ArrayList<TreePath>();
    
    if (info.getTreeUtilities().getReferenceClass(ref) != null) {
        result.add(new TreePath(ref.getTreePath(), info.getTreeUtilities().getReferenceClass(ref)));
    }
    
    List<? extends Tree> params = info.getTreeUtilities().getReferenceParameters(ref);
    
    if (params != null) {
        for (Tree et : params) {
            result.add(new TreePath(ref.getTreePath(), et));
        }
    }
    
    return result;
}
 

import com.sun.source.util.DocTreePath; //导入依赖的package包/类
@Override
public DocTree visitReference(ReferenceTree node, Element elementToFind) {
    DocTreePath currentDocPath = getCurrentDocPath();
    DocTrees trees = workingCopy.getDocTrees();
    Element el = trees.getElement(currentDocPath);
    ExpressionTree classReference = workingCopy.getTreeUtilities().getReferenceClass(currentDocPath);
    if((el == null || !(el.equals(elementToFind) || isMethodMatch(el))) && classReference != null) {
        el = trees.getElement(new TreePath(getCurrentPath(), classReference));
    }
    if (el != null && (el.equals(elementToFind) || isMethodMatch(el))) {
        ReferenceTree newRef;
        Name memberName = workingCopy.getTreeUtilities().getReferenceName(currentDocPath);
        List<? extends Tree> methodParameters = workingCopy.getTreeUtilities().getReferenceParameters(currentDocPath);
        if(el.getKind().isClass() || el.getKind().isInterface()) {
            newRef = make.Reference(make.setLabel(classReference, newName), memberName, methodParameters);
        } else {
            newRef = make.Reference(classReference, newName, methodParameters);
        }
        rewrite(currentDocPath.getTreePath().getLeaf(), node, newRef);
    }
    return super.visitReference(node, elementToFind);
}
 

import com.sun.source.util.DocTreePath; //导入依赖的package包/类
private void handleJavadoc(TreePath el) {
    if(el != null) {
        switch(el.getLeaf().getKind()) {
            case METHOD:
            case ANNOTATION_TYPE:
            case CLASS:
            case ENUM:
            case INTERFACE:
            case VARIABLE:
                DocCommentTree docCommentTree = info.getDocTrees().getDocCommentTree(el);
                if(docCommentTree != null) {
                    DocTreePath docTreePath = new DocTreePath(el, docCommentTree);
                    docScanner.scan(docTreePath, null);
                }
            default:
                break;
        }
    }
}
 

import com.sun.source.util.DocTreePath; //导入依赖的package包/类
private DocTreePath getTag(final JavadocContext jdctx, final int offset) {
    final DocTreePath[] result = new DocTreePath[1];
    final int normalizedOffset = skipWhitespacesBackwards(jdctx, offset);
    new DocTreePathScanner<Void, Void>() {
        @Override public Void scan(DocTree node, Void p) {
            if (   node != null
                && jdctx.positions.getStartPosition(jdctx.javac.getCompilationUnit(), jdctx.comment, node) <= normalizedOffset
                && jdctx.positions.getEndPosition(jdctx.javac.getCompilationUnit(), jdctx.comment, node) >= normalizedOffset) {
                result[0] = new DocTreePath(getCurrentPath(), node);
                return super.scan(node, p);
            }
            
            return null;
        }
    }.scan(new DocTreePath(jdctx.javadocFor, jdctx.comment), null);
    
    return result[0];
}
 

import com.sun.source.util.DocTreePath; //导入依赖的package包/类
private void insideTag(DocTreePath tag, JavadocContext jdctx) {
    switch (tag.getLeaf().getKind()) {
        case IDENTIFIER:
            if (tag.getParentPath() == null || tag.getParentPath().getLeaf().getKind() != Kind.PARAM)
                break;
            tag = tag.getParentPath();
            //intentional fall-through:
        case PARAM:
            insideParamTag(tag, jdctx);
            break;
        case SEE: case THROWS: case VALUE:
        case LINK: case LINK_PLAIN://XXX: was only unclosed???
            insideSeeTag(tag, jdctx);
            break;
        case REFERENCE:
            insideReference(tag, jdctx);
            break;
    }
}
 

import com.sun.source.util.DocTreePath; //导入依赖的package包/类
private void completeParamName(DocTreePath tag, String prefix, int substitutionOffset, JavadocContext jdctx) {
    if (EXECUTABLE.contains(jdctx.commentFor.getKind())) {
        List<? extends DocTree> blockTags = jdctx.comment.getBlockTags();
        ExecutableElement method = (ExecutableElement) jdctx.commentFor;
        for (VariableElement param : method.getParameters()) {
            String name = param.getSimpleName().toString();

            if (!containsParam(blockTags, name) && name.startsWith(prefix)) {
                items.add(JavadocCompletionItem.createNameItem(name, substitutionOffset));
            }
        }
        
        completeTypeVarName(jdctx.commentFor, prefix, substitutionOffset);
    } else if (jdctx.commentFor.getKind().isClass() || jdctx.commentFor.getKind().isInterface()) {
        completeTypeVarName(jdctx.commentFor, prefix, substitutionOffset);
    }
}
 

import com.sun.source.util.DocTreePath; //导入依赖的package包/类
@Override
public Void visitDocComment(DocCommentTree node, List<ErrorDescription> errors) {
    DocTreePath currentDocPath = getCurrentPath();
    Void value = super.visitDocComment(node, errors);
    DocSourcePositions sp = (DocSourcePositions) javac.getTrees().getSourcePositions();

    while (!tagStack.isEmpty()) {
        StartElementTree startTree = tagStack.pop();
        Name tagName = startTree.getName();
        HtmlTag tag = HtmlTag.get(tagName);
        if (tag.endKind == HtmlTag.EndKind.REQUIRED) {
            int s = (int) sp.getStartPosition(javac.getCompilationUnit(), currentDocPath.getDocComment(), startTree);
            int e = (int) sp.getEndPosition(javac.getCompilationUnit(), currentDocPath.getDocComment(), startTree);
            errors.add(ErrorDescriptionFactory.forSpan(ctx, s, e, TAG_START_UNMATCHED(tagName)));
        }
    }
    return value;
}
 

import com.sun.source.util.DocTreePath; //导入依赖的package包/类
private void checkParamsDocumented(List<? extends Element> list, List<? extends Tree> trees, DocTreePath docTreePath, Set<String> inheritedParams, List<ErrorDescription> errors) {
    if(foundInheritDoc) return;
    for (int i = 0; i < list.size() && i < trees.size(); i++) {
        if(ctx.isCanceled()) { return; }
        Element e = list.get(i);
        Tree t = trees.get(i);
        if (!foundParams.contains(e) && !inheritedParams.contains(e.getSimpleName().toString())) {
            boolean isTypeParam = e.getKind() == ElementKind.TYPE_PARAMETER;
            CharSequence paramName = (isTypeParam)
                    ? "<" + e.getSimpleName() + ">"
                    : e.getSimpleName();
            DocTreePathHandle dtph = DocTreePathHandle.create(docTreePath, javac);
            if (dtph != null) {
                errors.add(ErrorDescriptionFactory.forTree(ctx, t, MISSING_PARAM_DESC(paramName), AddTagFix.createAddParamTagFix(dtph, e.getSimpleName().toString(), isTypeParam, i).toEditorFix()));
            }
        }
    }
}
 

import com.sun.source.util.DocTreePath; //导入依赖的package包/类
private void checkThrowsDocumented(List<? extends TypeMirror> list, List<? extends ExpressionTree> trees, DocTreePath docTreePath, Set<String> inheritedThrows, List<ErrorDescription> errors) {
    if(foundInheritDoc) return;
    for (int i = 0; i < list.size(); i++) {
        if(ctx.isCanceled()) { return; }
        TypeMirror e = list.get(i);
        Tree t = trees.get(i);
        Types types = javac.getTypes();
        if (!foundThrows.contains(e) && !inheritedThrows.contains(e.toString())
                && (!(types.isAssignable(e, javac.getElements().getTypeElement("java.lang.Error").asType())
            || types.isAssignable(e, javac.getElements().getTypeElement("java.lang.RuntimeException").asType())))) {
            boolean found = false;
            for (TypeMirror typeMirror : foundThrows) {
                if(types.isAssignable(typeMirror, e)) {
                    found = true;
                    break;
                }
            }
            if(!found) {
                DocTreePathHandle dtph = DocTreePathHandle.create(docTreePath, javac);
                if(dtph != null) {
                    errors.add(ErrorDescriptionFactory.forTree(ctx, t, NbBundle.getMessage(Analyzer.class, "MISSING_THROWS_DESC", e.toString()), AddTagFix.createAddThrowsTagFix(dtph, e.toString(), i).toEditorFix()));
                }
            }
        }
    }
}
 

import com.sun.source.util.DocTreePath; //导入依赖的package包/类
@Override
protected void performRewrite(TransformationContext ctx) throws Exception {
    WorkingCopy javac = ctx.getWorkingCopy();
    DocTreePath path = dtph.resolve(javac);
    if(path == null) {
        LOG.log(Level.WARNING, "Cannot resolve DocTreePathHandle: {0}", dtph);
        return;
    }
    DocCommentTree docComment = path.getDocComment();
    TreeMaker make = javac.getTreeMaker();
    final List<DocTree> blockTags = new LinkedList<DocTree>();
    for (DocTree docTree : docComment.getBlockTags()) {
        if (docTree != path.getLeaf()) {
            blockTags.add(docTree);
        }
    }
    DocCommentTree newDoc = make.DocComment(docComment.getFirstSentence(), docComment.getBody(), blockTags);
    Tree tree = ctx.getPath().getLeaf();
    javac.rewrite(tree, docComment, newDoc);
}
 

import com.sun.source.util.DocTreePath; //导入依赖的package包/类
@Override
public Void visitThrows(ThrowsTree tree, Void ignore) {
    ReferenceTree exName = tree.getExceptionName();
    Element ex = env.trees.getElement(new DocTreePath(getCurrentPath(), exName));
    if (ex == null) {
        env.messages.error(REFERENCE, tree, "dc.ref.not.found");
    } else if (isThrowable(ex.asType())) {
        switch (env.currElement.getKind()) {
            case CONSTRUCTOR:
            case METHOD:
                if (isCheckedException(ex.asType())) {
                    ExecutableElement ee = (ExecutableElement) env.currElement;
                    checkThrowsDeclared(exName, ex.asType(), ee.getThrownTypes());
                }
                break;
            default:
                env.messages.error(REFERENCE, tree, "dc.invalid.throws");
        }
    } else {
        env.messages.error(REFERENCE, tree, "dc.invalid.throws");
    }
    warnIfEmpty(tree, tree.getDescription());
    return scan(tree.getDescription(), ignore);
}
 

import com.sun.source.util.DocTreePath; //导入依赖的package包/类
@Override @DefinedBy(Api.COMPILER_TREE)
public Void visitThrows(ThrowsTree tree, Void ignore) {
    ReferenceTree exName = tree.getExceptionName();
    Element ex = env.trees.getElement(new DocTreePath(getCurrentPath(), exName));
    if (ex == null) {
        env.messages.error(REFERENCE, tree, "dc.ref.not.found");
    } else if (isThrowable(ex.asType())) {
        switch (env.currElement.getKind()) {
            case CONSTRUCTOR:
            case METHOD:
                if (isCheckedException(ex.asType())) {
                    ExecutableElement ee = (ExecutableElement) env.currElement;
                    checkThrowsDeclared(exName, ex.asType(), ee.getThrownTypes());
                }
                break;
            default:
                env.messages.error(REFERENCE, tree, "dc.invalid.throws");
        }
    } else {
        env.messages.error(REFERENCE, tree, "dc.invalid.throws");
    }
    warnIfEmpty(tree, tree.getDescription());
    return scan(tree.getDescription(), ignore);
}
 

import com.sun.source.util.DocTreePath; //导入依赖的package包/类
void checkReference(ReferenceTree tree, List<? extends DocTree> label) {
    String sig = tree.getSignature();

    Element found = trees.getElement(new DocTreePath(getCurrentPath(), tree));
    if (found == null) {
        System.err.println(sig + " NOT FOUND");
    } else {
        System.err.println(sig + " found " + found.getKind() + " " + found);
    }

    String expect = "UNKNOWN";
    if (label.size() > 0 && label.get(0) instanceof TextTree)
        expect = ((TextTree) label.get(0)).getBody();

    if (!expect.equalsIgnoreCase(found == null ? "bad" : found.getKind().name())) {
        error(tree, "Unexpected value found: " + found +", expected: " + expect);
    }
}
 

import com.sun.source.util.DocTreePath; //导入依赖的package包/类
public DocCommentDuo getHtmlCommentDuo(Element e) {
    FileObject fo = null;
    if (e.getKind().equals(ElementKind.OTHER)) {
        fo = configuration.getOverviewPath();
    } else if (e.getKind().equals(ElementKind.PACKAGE)) {
        fo = configuration.workArounds.getJavaFileObject((PackageElement)e);
    }
    if (fo == null) {
        return null;
    }

    DocCommentTree dcTree = trees.getDocCommentTree(fo);
    if (dcTree == null) {
        return null;
    }
    DocTreePath treePath = trees.getDocTreePath(fo);
    return new DocCommentDuo(treePath.getTreePath(), dcTree);
}
 

import com.sun.source.util.DocTreePath; //导入依赖的package包/类
/**
 * Fully qualifies a javadoc reference, e.g. for replacing {@code {@link List}} with {@code {@link
 * java.util.List}}
 *
 * @param fix the fix builder to add to
 * @param docPath the path to a {@link DCTree.DCReference} element
 */
public static void qualifyDocReference(
    SuggestedFix.Builder fix, DocTreePath docPath, VisitorState state) {

  DocTree leaf = docPath.getLeaf();
  checkArgument(
      leaf.getKind() == DocTree.Kind.REFERENCE,
      "expected a path to a reference, got %s instead",
      leaf.getKind());
  DCTree.DCReference reference = (DCTree.DCReference) leaf;

  Symbol sym = (Symbol) JavacTrees.instance(state.context).getElement(docPath);
  if (sym == null) {
    return;
  }
  String refString = reference.toString();
  String qualifiedName;
  int idx = refString.indexOf('#');
  if (idx >= 0) {
    qualifiedName = sym.owner.getQualifiedName() + refString.substring(idx, refString.length());
  } else {
    qualifiedName = sym.getQualifiedName().toString();
  }

  replaceDocTree(fix, docPath, qualifiedName);
}
 

import com.sun.source.util.DocTreePath; //导入依赖的package包/类
@Override
public Description matchClass(ClassTree tree, final VisitorState state) {
  final DCTree.DCDocComment comment =
      ((JCTree.JCCompilationUnit) state.getPath().getCompilationUnit())
          .docComments.getCommentTree((JCTree) tree);
  if (comment == null) {
    return Description.NO_MATCH;
  }
  final SuggestedFix.Builder fix = SuggestedFix.builder();
  new DocTreePathScanner<Void, Void>() {
    @Override
    public Void visitLink(LinkTree node, Void aVoid) {
      SuggestedFixes.qualifyDocReference(
          fix, new DocTreePath(getCurrentPath(), node.getReference()), state);
      return null;
    }
  }.scan(new DocTreePath(state.getPath(), comment), null);
  if (fix.isEmpty()) {
    return Description.NO_MATCH;
  }
  return describeMatch(tree, fix.build());
}
 

import com.sun.source.util.DocTreePath; //导入依赖的package包/类
private void appendReference(StringBuilder sb, ReferenceTree ref, List<? extends DocTree> label, TreePath docPath, DocCommentTree doc, DocTrees trees) {
    String sig = ref.getSignature();
    if (sig != null && sig.length() > 0) {
        if (sig.charAt(0) == '#') { //NOI18N
            sig = sig.substring(1);
        }
        sig = sig.replace('#', '.'); //NOI18N
    }
    Element element = trees.getElement(DocTreePath.getPath(docPath, doc, ref));        
    if (element != null) {
        createLink(sb, element, label == null || label.isEmpty() ? sig : inlineTags(label, docPath, doc, trees, null)); //NOI18N
    } else {
        sb.append(label == null || label.isEmpty() ? sig : inlineTags(label, docPath, doc, trees, null));
    }
}